Previous section.

Systems Management: Distributed Software Administration
Copyright © 1997 The Open Group

Common Definition for Utilities

This chapter defines the common definitions and behaviors of the utilities defined in this Software Administration specification. These utilities conform to the utility syntax guidelines in POSIX.2. The utilities themselves are defined in Software Administration Utilities .

Synopsis

The following is the general synopsis format for the utilities:

<sw_utility> [-d|-r] [-p] [-u] [-a attribute] [-c catalog] [-s source[
[-f file][-t targetfile][-x option=value][-X options_files]
[software_selections][@ targets]

Description

The utilities all operate on software_selections in source or target software_collections or both.

Options

Each of the utilities in this standard does not support all of the options shown below. Each utility supports the options indicated in its synopsis section and those indicated after the description of the options in this section. All options can be repeated. Except where otherwise stated within this Software Administration specification, the behavior for repeated options is undefined. In addition to those shown below, the -W (capital-W) option is reserved for implementation extensions. See POSIX.2.

-a attribute

Used to specify the attributes on which the utility operates.

This option can be used multiple times to specify a set of attributes.

Applies to swlist, and swmodify.

-c catalog

Used to specify a file with the software definition file syntax or directory with the exported catalog structure.

This is where software catalog information (metadata) is to be stored to or retrieved from. If this information fits into one file, then the catalog can be a file, otherwise it will be a directory. See Software Packaging Layout and Software Definition File Format .

Applies to swask, swconfig, swinstall, swlist, and swmodify.

-d
Indicates to the utility that the operation is on a distribution instead of installed_software.

Applies to swlist, swmodify, swremove, and swverify.

-f file

Reads the list of software_selections from file.

If this option is specified multiple times, all the software specified by each file is included in the operation. All of the software specified by using this option, as well as all the software specified directly as arguments to the utility, is included in the operation.

The file contains one software selection per line, where a software selection uses the syntax for software_spec defined in Software Specification and Logic . Blank lines is ignored. Within the file, the # (pound) character acts as a comment character. On any line containing a # (pound) character, all characters that follow the # (pound) character up to, but excluding, the next <newline> , is ignored.

Applies to all utilities.

-p
Previews the operation without making any permanent modifications to the target.

An implementation should run any control scripts that are executed as part of the selection or analysis phase of the command being previewed, but does not run any that are executed in the execution phase.

This option can be used with any or all of the other options to understand the impact of an operation before performing it.

Applies to swconfig, swcopy, swinstall, swmodify, swpackage, and swremove.

-r
Indicates to the utility that the operation is on an installed_software object located at an alternate root, instead of either a distribution or the installed_software object located at / .

Applies to swinstall, swlist, swmodify, swremove, and swverify.

-s source

Specifies the software source for the operation.

For swinstall, swask, and swcopy a source can be specified using the syntax in Source and Target Specification and Logic . For swpackage, the source is a product specification file.

Applies to swask, swcopy, swinstall, and swpackage.

-t targetfile

Reads the list of targets from targetfile.

If this option is specified multiple times, all the targets specified by each file is included in the operation. All of the targets specified by using this option, as well as all the targets specified directly as arguments to the utility, is included in the operation.

The file contains one target per line, where a target uses the syntax for software_collection_spec defined in Source and Target Specification and Logic . Blank lines is ignored. Within the file, the # (pound) character acts as a comment character. On any line containing a # (pound) character, all characters that follow the # (pound) character up to, but excluding, the next <newline> , is ignored.

Applies to swconfig, swcopy, swinstall, swlist, swmodify, swpackage, swremove, and swverify.

-u
This is the option used to specify undo or delete behavior to a utility.

Applies to swconfig and swmodify.

-x option=value

Used to override the value of an extended option in the defaults file.

The extended options supported are described in Extended Options . This option can be specified multiple times. If any extended option is defined more than once, the precedence rules from Precedence for Option Specification is used.

Applies to all utilities.

-X options_file

Used to override the defaults specified in the system defaults file.

The options supported are described in Extended Options . This option can be specified multiple times. If any extended option from any file is defined more than once, the precedence rules from Precedence for Option Specification is used.

The file has the format defined in Extended Options Syntax .

Applies to all utilities.

Non-interactive Operation

All utilities except swask are by default non-interactive. The swinstall and swconfig utilities also define interactive modes for executing request scripts independent of the swask utility.

The way in which swinstall, swcopy and swpackage utilities handle multiple volumes for sources or targets is implementation defined.

Operands

There are two types of operands that may be specified on the command line, software_selections and targets. The software_selections refer to the software objects (bundles, products, subproducts and filesets) to be operated on. The targets refer to the target software_collections where the software selections are applied. These two operand types is separated by the @ operand. With the exception of swpackage, the behavior of all utilities defined in this Software Administration specification is undefined if no software_selections are provided.

Software Specification and Logic

The following specifies the syntax for software selections in utilities (software_spec) and in dependency specifications (dependency_spec). This syntax is applied by the utilities to search a software_collection catalog for software. Note that the tokens shown below are defined in the Glossary. 1

%token    FILENAME_CHARACTER_STRING     /* as defined in Glossary */
%token    NEWLINE_STRING                /* as defined in Glossary */
%token    PORTABLE_CHARACTER_STRING     /* as defined in Glossary */
%token    SOFTWARE_PATTERN_MATCH_STRING /* as defined in Glossary */
%token    WHITE_SPACE_STRING            /* as defined in Glossary */


%start  software_selections
%%


software_selections      : software_selections ws software_spec
                         | software_spec
                         ;


software_spec            : bundle_software_spec
                         | product_software_spec
                         ;

bundle_software_spec     : bundle_qualifier version
                         | bundle_qualifier '.' product_qualifier  version
                         ;

bundle_qualifier         : bundle_qualifier '.' bundle_tag
                         | bundle_tag
                         ;

product_software_spec    : product_qualifier version
                         ;

product_qualifier        : product_tag subproduct_qualifier fileset_qualifier
                         ;

subproduct_qualifier     : /* empty */
                         | subproduct_qualifier '.' subproduct_tag
                         | '.' subproduct_tag
                         ;

fileset_qualifier        : /* empty */
                         | '.' fileset_tag
                         ;

bundle_tag               : sw_pattern
                         ;

product_tag              : sw_pattern
                         ;

fileset_tag              : sw_pattern
                         ;

subproduct_tag           : sw_pattern
                         ;

version                  : /* empty */
                         | ',*'
                         | version_qualifier
                         ;

version_qualifier        : version_qualifier ver_item
                         | ver_item
                         ;

ver_item                 : ',' ver_id '='
                         | ',' ver_id '=' sw_pattern
                         | ',' 'r' rel_op dotted_string
                         ;

sw_pattern               : SOFTWARE_PATTERN_MATCH_STRING
                         ;

ver_id                   : 'r'  |  'a'   | 'v'   | 'l'   | 'q'
                         ;

rel_op                   : '==' | '!=' | '>=' | '<=' | '<' | '>'
                         ;

dotted_string            : FILENAME_CHARACTER_STRING
                         ;

ws                       : WHITE_SPACE_STRING
                         ;



%start  dependency_spec
%%


dependency_spec          : dependency_spec '|' software_spec
                         | software_spec
                         ;


If the software_spec identifies a bundle, product or subproduct software object, then all filesets contained within that object are included as part of that specification. For software selections, this means that all of these filesets are included. For dependency specifications, this means that all of these filesets are needed in order to meet the dependency.

If a software_spec identifies a set of filesets that is less that the entire set of filesets within a bundle or product, the software_spec identifies a partial bundle or product.

Only the specified strings is used to generate a software_spec. Blanks do not appear between items. The sw_pattern and dotted_string must be enclosed in quotes if they contain blanks or commas. The bundle_tag, product_tag, subproduct_tag, and fileset_tag consists of one or more characters from the filename character set, with the exception that the following three characters  . , :  (period, comma, and colon) are not used.

Searching a software_collection catalog for software using a software_spec yields a list of zero or more software objects that match the software_spec . The rules to be used in the search are the following:

  1. The software_spec is compared against software in the software collection. The leftmost sw_pattern of the software_spec is matched against the tag attribute of all bundles and products in the software collection. All objects that match are initially included for consideration. If the sw_pattern does does not match any bundle or product, no objects are included.

    The version specified in the software_spec is compared against the revision, architecture, vendor_tag, location, and qualifier attributes of the objects matching the leftmost sw_pattern . If any ver_id in the software_spec does not match its corresponding attribute, that object is removed from consideration. If the same ver_id is given more than once, all the comparisons specified are performed and all must succeed to be considered a match.

    Table: Software_spec Version Identifiers

    ver_id Attribute
    r revision
    a architecture
    v vendor_tag
    l location
    q qualifier

    An implementation may define additional ver_id items along with the attributes and objects to which they apply.

    For each object still included for consideration, each successive sw_pattern , left to right, is applied to the bundles, products, subproducts and filesets within that object. The same sw_pattern may match multiple bundle, product, subproduct and fileset objects. If any sw_pattern does not match any objects within the current object, the current object is removed from consideration. If a fileset matches a sw_pattern but there is still an unmatched sw_pattern in the software_spec , that fileset is not selected.

    When there are no more sw_patterns left in the software_spec , all the objects identified by the rightmost sw_pattern of the software_spec are included in the list of software that match the software_spec .

  2. The comparison performed when the operator is = will be a software pattern match as described in the Glossary. If the ver_id is specified and the value is an empty string, then the comparison is successful only if the corresponding attribute is not specified. See Fully-qualified Software_spec .

  3. When rel_op is used,2 the comparison is performed on the specified attribute by dividing it into segments separated by the  .  (period) character. If there is no period in an attribute, it contains one segment. The segments are compared with the corresponding segments of the dotted_string . If all characters in both segments to be compared are decimal digit characters (0-9),3 the comparison is based on the decimal numeric value of the segments, starting with the leftmost segment. If either segment includes a any character other than a decimal digit character, a string comparison is made to determine the relation. String comparisons is made using, as a collation sequence, the order of characters in [??]. If one operand has fewer segments than the other, the unmatched segments is compared against the value 0 (zero).

  4. When applied to software in installed software collections, use of either the l (location) or q (qualifier) ver_id causes comparison with the value of the location or qualifier attribute respectively for each product or bundle in the installed_software object.

    For distributions, use of either the l (location) or q (qualifier) ver_id is ignored for the purpose of comparisons. Although not used for comparisons, the location and qualifier ver_ids are used by the swinstall utility as the location attribute for installing the software and the qualifier attribute for the software respectively.

  5. When software selections are applied to a source or target, and a software_spec resolves to more than one software object, then the software_spec is considered ambiguous. An ambiguous selection may be elective or incidental. An elective ambiguous selection occurs when a sw_pattern in a software_spec contains a wildcard character or when the version contains a rel_op , or when the sw_pattern is missing. In all other cases the selection is an incidental ambiguous selection. An incidental ambiguous selection is only valid for swlist, and for other utilities generates an event.
    (SW_ERROR: SW_SELECTION_NOT_FOUND_AMBIG)

  6. If the software_spec begins with a bundletag definition, then that bundle definition is copied or installed with swcopy or swinstall. Thus, a software_spec which matches one or more bundles can be used with all other utilities, but only if they were explicitly installed or copied. However, all subproduct definitions are copied or installed independently of whether they were explicitly selected. Thus, a software_spec which matches subproducts can always be used on existing products.

For both bundles and subproducts, if some part of their contents exist, then the selection can be found; therefore, any operation will succeed. If none of their contents exist, then the selection cannot be found; therefore, the operation will fail (for those selections not found) as defined in the individual Extended Description section of each utility.

Fully-qualified Software_spec
A fully-qualified software_spec is one in which no fields contain a shell pattern match string and all version distinguishing attributes are specified as "ver_id=<value>" (if a value is supplied) or as "ver_id=" (if no value is supplied or if the value supplied is an empty string). Note that a fully-qualified software_spec always identifies a software object unambiguously.

When a software_spec is generated by swlist, only the following tags are included: the product tag for products, the bundle tag for bundles, the product and fileset tag for filesets, and the product and subproduct tag for subproducts.

Software Compatibility
Products contain attributes (.I os_name , os_version, os_release, and machine_type) related to the uname() function defined by POSIX.1. These attributes are used by the swinstall, swconfig, and swverify utilities to determine if software is compatible with a target host. A product is considered compatible with a target host if each of the uname attributes of the product contains a pattern in its definition that matches the corresponding values returned by the uname() function on the target host. If any of these attributes is undefined, it is considered to match any target host. The compatibility test applies to all components of a product, including subproducts and filesets.

Bundles, like products, possess uname attributes. The values of the bundle uname attributes determine the compatibility of the bundle in conjunction with the corresponding attributes of products within the bundle. A product specified as part of a bundle is considered compatible if both the product and bundle uname attributes designate that the software is compatible. As with products, if any of these attributes is undefined, it is considered to match any target host.

Source and Target Specification and Logic

Source and target software_collections are specified using the following syntax.

%token          HOST_CHARACTER_STRING     /* as defined in Glossary */
%token          PATHNAME_CHARACTER_STRING /* as defined in Glossary */
%start  target
%%

target          : software_collection_spec
                ;


software_collection_spec : HOST_CHARACTER_STRING ':' PATHNAME_CHARACTER_STRING
                         | HOST_CHARACTER_STRING ':'
                         | HOST_CHARACTER_STRING
                         | PATHNAME_CHARACTER_STRING
                         ;

%start  source
%%

source          : software_collection_spec
                ;


The : (colon) is required if both the host and pathname are specified, or if the host portion starts with a / (slash). The pathname portion is an absolute path. The colon is not allowed by itself.

The HOST_CHARACTER_STRING portion refers to the implementation defined identifier for a host. If it is not specified, then the local host is assumed.

The PATHNAME_CHARACTER_STRING portion refers to the software_collection path attribute (the location on the host of the distribution or installed_software object).

When the PATHNAME_CHARACTER_STRING is not specified for installed_software, the directory / is used.

A PATHNAME_CHARACTER_STRING other than / for an installed_software object is referred to as an alternate root directory. When the PATHNAME_CHARACTER_STRING is not specified for source distributions, the value of the distribution_source_directory default option is used. When the PATHNAME_CHARACTER_STRING is not specified for target distributions, the value of the distribution_target_directory default option is used.

For installed_software objects, the value of the installed_software_catalog option is used to further clarify which installed software object is actually being targeted. Multiple installed_software objects may share the same path attribute, but they have separate catalog information because they are distinct objects. The installed_software path attribute prepended to the value of the installed_software_catalog option forms the key for the object into the catalog information. Use of the installed_software_catalog is independent of the -c option.

An implementation supports source and target distributions in the directory format described in Serial Format and Multiple Media , for all utilities. An implementation supports a source distribution in the serial format for swask, swinstall, and swcopy utilities. An implementation supports a target distribution in the serial format for swlist, swcopy, and swpackage. Whether data on an existing target distribution in serial format is overwritten or merged is implementation defined. An implementation need not support a target distribution in the serial format for swverify, swremove, and swmodify. Unless otherwise stated, support for serial distributions includes support for both extended tar and extended cpio archives. See Serial Format and Multiple Media . The format of these archives is defined in POSIX.1.

External Influences

Defaults and Options Files

The defaults file allows setting of system wide defaults for extended options that define information (location of files and other objects), behavior, and policy control items for the utilities defined in this Software Administration specification. The location of the defaults file is implementation defined. An implementation may define separate defaults files for each task. These options also may be specified for each user in the manager role in the file $HOME/.swdefaults .

Extended Options

The utilities in this Software Administration specification support the following extended options as noted. If a default value is defined, it is listed after the = (equal sign).

allow_downdate=false

Controls the ability to replace a fileset with one of a lower revision.

If allow_downdatefalse, do not allow installation of a lower revision of a fileset that is already installed at a higher revision in this location.

If allow_downdatetrue, allow installation of a lower revision of a fileset.

Applies to swinstall.

allow_incompatible=false

Controls the ability to install software that is not compatible with the underlying operating system, as defined in Software Compatibility .

If allow_incompatiblefalse, do not allow incompatible software to be operated on if the installed_software path is /.

If allow_incompatibletrue, then attempt the operation.

Applies to swinstall, swconfig, and swverify.

allow_multiple_versions=false

Controls the ability to configure multiple versions of a product.

If allow_multiple_versionsfalse, do not attempt to configure a second version of a fileset if one is already configured. If allow_multiple_versionstrue, then attempt the operation.

Applies to swconfig.

ask=false

Controls the ability to execute request scripts for selected software.

If ask=false, the utilities do not run any request scripts for selected software. The behavior of swask for ask=false, is undefined.

If ask=true, the utilities execute all request scripts for selected software after resolving selections, but before initiating analysis on the targets. This is the default value for swask.

If ask=as_needed, the utilities execute any request scripts for selected software that does not already have a response file in the control directory where the script would be executed. The location of this control directory depends on whether the -c option has been set.

Applies to swask, swconfig, and swinstall.

autoreboot=false

Controls automatic rebooting of the target host. If autoreboot=false, do not automatically reboot the target host, even if a fileset installed requires a reboot to take effect.

If autoreboot=true, automatically reboot the target host if a fileset requiring a reboot is installed.

Applies to swinstall.

autorecover=false

Controls automatic recovery if an error occurs during install, as specified in section swinstall .

If autorecover=false and an install error occurs, no error recovery is provided at all, not even as an extension to this Software Administration specification. Consequently, no attempt should be made to restore the original state of the system prior to install. The value of the fileset state attribute is set to corrupt .

If autorecover=true and an error occurs, then for any fileset having an install error, implementations will execute the unpostinstall script (if the postinstall script had been run) and the unpreinstall script,4 restore the files within the fileset from a copy saved prior to the failed install, and the restore the value of the state attribute. After recovery of the applicable filesets, installation can continue with the rest of the filesets in that product and the rest of the products in the software selections.

Applies to swinstall.

autorecover_product

Like the autorecover option, this option will recover a complete product to the previous state, including running the appropriate unpreinstall and unpostinstall scripts, if the product postinstall fails.

This option differs from the autorecover option in that the product will be recovered to its previous state if any fileset has a script error or a file loading error. This means the install results in either a fully updated product or the previous product. With the POSIX autorecover option, only that fileset is recovered, and the other filesets are attempted, resulting in a partially updated product.

autoselect_dependencies=as_needed

Controls automatic dependency selection.

If autoselect_dependencies=true, (the default for all utilities except swinstall and swcopy), prerequisite and corequisite dependencies are autoselected if possible during the selection phase. Autoselection of a dependency is done using the software selection logic found in Software Specification and Logic . These dependencies are then operated on as if they were selected explicitly.

If autoselect_dependencies=as_needed, (the default for swinstall and swcopy), then autoselected dependencies is only operated upon if the dependency is not already met on the target. This value only applies to swcopy and swinstall.

If autoselect_dependencies=false, then no dependencies are autoselected for operation. For install and copy, if the dependencies are not already met on the target, an error occurs when enforce_dependencies=true.

Applies to swask, swconfig, swcopy, swinstall, and swverify.

autoselect_dependents=false

Controls automatic dependency selection.

If autoselect_dependents=true , dependent software (software that depends on this software) will be autoselected if possible during the selection phase. This dependent software is operated upon unless the dependency can be met by other software on the target. If dependent software exists that can not still meet its dependencies through other unselected software, then an error occurs.

If autoselect_dependents=false, no dependent software is autoselected.

Applies to swconfig, and swremove.

check_contents=true

Controls verification of file contents.

If check_contents=true, then swverify checks the mtime, size and cksum attributes of files.

If check_contents=false, then swverify does not check the attributes.

This applies to both distribution and installed_software files.

Applies to swverify.

autoselect_patches=true

This option causes all patches (except for those that are superseded by other patches) that have an ancestor attribute defined for selected software to be automatically selected as well during swinstall and swcopy operations. The default setting for this option is
true.

Applies to swinstall and swcopy.

check_permissions=true

Controls verification of file permissions.

If check_permissions=true, then swverify checks the owner, uid, group, gid, mode attributes of files, and the major and minor attributes of device files.

If check_permissions=false, then swverify does not check the attributes.

This only applies to installed_software files.

Applies to swverify.

check_requisites=true

Controls verification of fileset requisites.

If check_requisites=true then swverify checks the prerequisites, corequisites, and exrequisites attributes of files.

If check_requisites=false, then swverify does not check the attributes.

This applies to both distribution and installed_software.

Applies to swverify.

check_scripts=true

Controls the running of the
verify script.

If check_scripts=true, then swverify runs the vendor supplied verify script for each fileset when operating on installed_software objects. When the F option of swverify is used, the vendor supplied fix script is also executed.

If check_scripts=false, then swverify does not run the scripts.

Applies to swverify.

check_volatile=false

Controls check of volatile files.

If check_volatile=true, then swverify includes files whose is_volatile attribute is set to true in its check of files and their attributes.

If check_volatile=false, then swverify does not include volatile files. This is useful to eliminate potentially "spurious" reports from swverify when the only file changes are those to files known in advance to be volatile.

Applies to swverify.

compress_files=false

Controls whether uncompressed files are to be compressed in the target distribution, as specified by the value of compression_type.

If compress_files=true, then all files except those that have a compression_state of not_compressible are compressed, or remain compressed.

If compress_files=false, uncompressed files are not compressed, and the status of any compressed file is determined by the value of uncompress_files.

Applies to swcopy.

compression_type=implementation_defined_value

Specifies the compression type used to compress the software files.

The values supported for compression_type are implementation defined.

The way in which an implementation uses this value to implement or execute the compression or uncompression of a file is undefined.

Applies to swcopy.

defer_configure=false

Controls automatic configuration at install.

If defer_configure=false, software being installed is also configured when the root directory is  / .

If defer_configure=true, then the software is installed but not configured, and may require configuration (using swconfig) before being used.

Applies to swinstall.

defer_deleting_files=false

This option defers the deleting files of type "delete file" by during install or update.

Applies to swinstall.

distribution_source_directory=implementation_defined_value

Specifies the default distribution directory.

When a source specification does not contain a path specification, the value of this extended option is used as as the default source distribution directory. When a source specification does contain a path specification, it is used.

Applies to swask, swcopy, and swinstall.

distribution_target_directory=implementation_defined_value

Specifies the default distribution target.

When a target specification does not contain a path specification, the value of this extended option is used as the default distribution target. When a target specification does contain a path specification, it is used. For swpackage, this is used only when media_type=directory.

Applies to swcopy, swlist, swmodify, swpackage, swremove, and swverify.

distribution_target_serial=implementation_defined_value

Specifies the default distribution target.

When a target specification does not contain a path specification and media_type=serial, the value of this extended option is used as the default distribution target. When a target specification does contain a path specification, it is used.

Applies to swpackage.

enforce_dependencies=true

Controls the enforcement of dependency specifications.

If enforce_dependenciesr=true, no utility except swremove and the unconfigure option of swconfig proceeds unless necessary dependencies have been selected, or already exist in the proper state on the target. The swremove utility and the unconfigure portion of the swconfig utility does not proceed if operating on the selected software leaves dependent software with their dependencies unresolved beyond what existed before the utility was executed.

If enforce_dependencies=false, then all utilities proceed even if some dependencies are not met. Enforcement of dependencies is independent of whether or not they were autoselected.

Applies to swconfig, swcopy, swinstall, swremove, and swverify.

enforce_dsa=true

Controls the handling of disk space analysis errors.

If enforce_dsa=true, the implementation defined error handling procedure is invoked when the disk space analysis indicates there is not enough disk space.

If enforce_dsa=false, then the operation is attempted even if disk space analysis indicated a problem.

Applies to swcopy, swinstall, and swpackage.

enforce_locatable=true

Controls the handling of errors when relocating a non-relocatable fileset.

If enforce_locatable=true, an error is generated if an attempt is made to relocate a non-relocatable fileset.

If enforce_locatable=false, an attempt is made to relocate the fileset in any case.

Applies to swinstall, and swverify.

enforce_scripts=true

Controls the handling of errors generated by scripts.

If enforce_scripts=true, the implementation defined error handling procedure is invoked when the vendor supplied scripts return an error.

If enforce_scripts=false, all script errors is treated as warnings, and the utility attempts to continue operation.

Applies to swinstall, and swremove.

files=

Lists the pathnames of file objects to be added or deleted.

If files='file1 file2 file3 ...', then catalog information for those files is added or deleted. When files are added, the attributes of the file are retrieved from the actual file on the installed file system. File objects being added or deleted can also be specified in the INFO file format. There is no supplied default.

Applies to swmodify.

follow_symlinks=false

Controls the following of symbolic links

If follow_symlinks=false, then do not follow any symbolic links that may exist in the packaging source.

If follow_symlinksr=etrue, then attempt to follow symbolic links.

Applies to swpackage.

installed_software_catalog=implementation_defined_value

Specifies installed software catalog.

This extended option, along with the installed_software path attribute, defines the logical installed_software object upon which the utility is operating. This extended option is resolved relative to the PATHNAME_CHARACTER_STRING portion of the targets operand. See Source and Target Specification and Logic .

This option allows an implementation to define where the catalog information is stored. This option also allows multiple logical installed_software objects to share the PATHNAME_CHARACTER_STRING where the software is installed.

Applies to swask, swconfig, swinstall, swlist, swmodify, swremove, and swverify.

logfile=implementation_defined_value

Specifies the location of the the logfile for the management role.

Logfile structure for all roles, logfile locations for other roles, and the effect of this option on logfile location is implementation defined.

Applies to all utilities except swlist.

loglevel=1

Controls the amount of output sent by the utility to log files (not to stdout and stderr).

See Logging .

Applies to all utilities except swlist.

match_target=false

When set to true, this option adds software items from the source depot to the selection list that have the same ancestor as software already installed, if the ancestor software is installed in only a single location.

Applies to swinstall.

media_capacity=0

The storage capacity in megabytes of the output media.

A value of 0 (zero) indicates an infinite capacity.

Applies to swpackage.

media_type=directory

The default media type.

If media_type=directory, the distribution is located in the value of the distribution_target_directory option.

If media_type=serial, the distribution is located in the value of the distribution_target_serial option.

Applies to swpackage.

one_liner=implementation_defined_value

Specifies attributes to list.

The one_liner option specifies the attributes to list by default when neither v and a attribute options are specified. Only attributes that apply to each object listed are included for that object. At least one of the tag attribute (of products, subproducts, filesets and control scripts) or the path attribute (of files) is included. The order of attributes in the output listing need not be the order of the attributes specified in this option. The listing format used by one_liner is undefined.

Applies to swlist.

patch_commit=false

When set to true, this removes the saved files for the patches specified in the software selections operands, meaning that patch can no longer be rolled back.

Applies to swmodify.

patch_save_files=true

This option allows the user to save existing files, enabling rollback of patches, or to not save files (meaning that patches can not be rolled back).

Applies to swinstall.

patch_filter=*

This option can only be used in conjunction with the options autoselect_patches or patch_match_target. This option is used to filter the automatically selected patches to only those meeting the tag, version and category filtering criteria specified. The default value of this option is "*" (all patches).

Applies to swinstall and swcopy.

patch_match_target=false

This option corresponds to the update match_target option, automatically selecting patches that have ancestors defined for software currently installed or in the depot. Patches that are superseded by other patches are not included in the selections. The default value of this option is false.

Applies to swinstall and swcopy.

reconfigure=false

Controls reconfiguring of software.

If reconfigure=false, do not reconfigure software if it is already in the configured state.

If reconfigure=true, reconfigure the software even if it is already in the configured state.

Applies to swconfig.

recopy=false

Controls copying of filesets.

If recopy=false, do not copy a fileset that is already available on the target at the same version.

If recopy=true, then copy the fileset in any case.

Applies to swcopy.

reinstall=false

Controls reinstallation of filesets.

If reinstall=false, do not install a fileset that already has the same version already installed.

If reinstall=true, then reinstall the fileset even if this version is already installed.

Applies to swinstall.

reinstall_files=false

When set to true, this option directs the utility to reinstall (or recopy) each file independent of whether the file is already installed (or in the depot) correctly. When set to false, if the file is already installed (based on mtime, size and cksum), it is not reinstalled (or retransferred over the network for distributed install).

Applies to swinstall, swcopy and swpackage.

reinstall_files_use_cksum=true

This option is only applicable if reinstall_files=false. When set to true, this option directs the utility to include a checksum check when determining if the file is up to date. When set to false, only size and mtime are checked.

Applies to swinstall, swcopy and swpackage.

save_modified_files=false

This option compares the catalog information for each file in each fileset that is being updated against the actual size and cksum attributes of the installed files, and saves those files that differ. Where these files are saved is implementation defined.

Applies to swinstall.

saved_files_directory=<implementation_defined_value>

This option allows the user to specify where the saved files are retained. This directory is also stored in the installed software catalog for a patch fileset, so the correct location can be identified when removing or committing a patch, or updating a patches' ancestor.

This value should be an absolute path. If the value is relative or an empty string, the behavior is undefined.

Applies to swinstall.

select_local=true

Controls default selection of target.

If select_local=true, and no targets are specified, then the local host is selected as the target.

If select_local=false, then the local host is not automatically included.

Applies to all utilities except swask and swpackage.

software=

Specifies a default set of software_selections for the utility.

Applies to all utilities in this Software Administration specification.

targets=

Specifies a default set of targets for the utility.

See the select_local option.

Applies to all utilities in this Software Administration specification except swpackage.

uncompress_files=false

Controls whether compressed files are to be uncompressed in the target distribution, as specified by the value of the compression_type attribute of the file.

If uncompress_files=false, all files with a compression_state attribute value of compressed remain compressed, and the status of uncompressed files is determined by the value of compress_files.

If uncompress_files=true, all compressed files are uncompressed before being written to the target distribution.

Applies to swcopy.

verbose=1

Controls the amount of output sent by the utility to stdout and stderr, but not to log files.

For values which are non-negative integers, an increase in verbose does not decrease the information sent stdout and stderr. All implementations support the values 0 (zero) and 1 (one). If verbose=0, nothing is written to either stdout or stderr. The effect of other values of verbose is undefined. See also Stdout , and Stderr .

Applies to all utilities in this Software Administration specification.

Extended Options Syntax

The syntax is the same for options specified on the command line and for those specified in the options file. Individual options use this syntax:

%token    FILENAME_CHARACTER_STRING /* as defined in Glossary */
%token    PORTABLE_CHARACTER_STRING /* as defined in Glossary */
%token    SHELL_TOKEN_STRING        /* as defined in Glossary */
%token    WHITE_SPACE_STRING        /* as defined in Glossary */


%start  software_option
%%


software_option          : command_qualifier  keyword '=' value
                         ;

command_qualifier        : /* empty */
                         | command '.'
                         ;

value                    : multi_value
                         | single_value
                         ;

multi_value              : value ws single_value
                         | single_value
                         ;

single_value             : SHELL_TOKEN_STRING
                         ;

command                  : FILENAME_CHARACTER_STRING
                         ;

keyword                  : FILENAME_CHARACTER_STRING
                         ;

ws                       : WHITE_SPACE_STRING
                         ;


With respect to this syntax, the following apply:

When specified on the command line, multiple option specifications can be included after a single -x option if included in quotes and separated by white space. Multiple -x options can also be used.

For option and defaults files, blank lines and all comment text are ignored. Comment text is any sequence of characters beginning with a # (pound) character which is neither escaped nor quoted, and continuing through the end of that line.

If the white space between single values contains a <newline> , either it is "escaped" or the entire value is quoted.

The following are examples of this syntax:

loglevel=1 allow_incompatible=false autoselect_dependencies="as_needed" software="Foo,r=1.2,a=hp-ux bar,a=Aix_3.2" targets="hosta:/ hostb hostc:" software="Foo,r=1.2,a=hp-ux bar,a=Aix_3.2" targets="hosta:/ hostb hostc: "
Precedence for Option Specification
Multiple option or operand specifications have a precedence that defines which specifications are used.

Only the option specifications with the highest level of precedence are used for each options and operands. The precedence is in increasing order:

  1. System defaults file

  2. User defaults file

  3. Options file

  4. Command line options and operands

If there are multiple instances of options at any particular level, then the following rules apply:

Input Files

The definitions for the swpackage utility (see tagmref_swpackage ) and the swmodify utility (see tagmref_swmodify ) respectively specify additional input files specific to those utilities.

Access and Concurrency Control

An implementation of this Software Administration specification allows a user to create, modify, delete, and access a catalog that describes a software object located where it is permissible for that user to respectively create, modify, delete, and access files. Other authorization, authentication and concurrency control requirements and mechanisms are undefined within this Software Administration specification. This Software Administration specification does provide event definitions that an implementation can use for access and concurrency control errors.

If the user of a utility does not have the proper authorization to run a utility, access a software_collection, or access software objects within that utility, the target may generate an event (SW_ERROR: SW_ACCESS_DENIED).

If the concurrency control mechanism prevents simultaneous operation on a software collection or software object, the target may generate an event (SW_ERROR: SW_CONFLICTING_SESSION_IN_PROGRESS).

If the command will proceed anyway, then the target may generate an event (SW_WARNING: SW_CONFLICTING_SESSION_IN_PROGRESS).

If the concurrency control mechanism fails for other reasons, the target may generate an event (SW_ERROR: SW_SOC_LOCK_FAILURE).

Environment Variables

Environment variables are a feature of this Software Administration specification inherited from POSIX.1. The following environment variables affects the execution of all the utilities defined in this Software Administration specification:

LANG

This variable determines the locale to use for the locale categories when both LC_ALL
and the corresponding environment variable (beginning with LC_) do not specify a locale.

See POSIX.2.

LC_ALL

This variable determines the locale to be used to override any values for locale categories specified by the settings of LANG or any environment variables beginning with LC_.

LC_CTYPE

This variable determines the interpretation of sequences of bytes of text data as characters (for example, single versus multibyte characters in values for vendor defined attributes).

LC_MESSAGES

This variable determines the language in which messages should be written.

LC_TIME

This variable determines the format of dates (create_date and mod_date) when displayed by swlist.

It should also be used by all utilities when displaying dates and times in stdout, stderr, and logging.

TZ

This variable determines the time zone for use when displaying dates and times.

External Effects

Control Script Execution and Environment

The utilities defined in this Software Administration specification causes control files to be interpreted according to the following rules:

  1. If no value is set for the control_file.interpreter attribute, or if the value is set to either the empty string or sh, the script is interpreted by the POSIX.2 shell.

  2. If the value of control_file.interpreter is set to a value other than the empty string or sh, then the utility determines the availability of the interpreter in an operating system dependent fashion equivalent to searching PATH for an executable file with a filename equivalent to the value of control_file.interpreter. If the interpreter is determined to be available, the control file is interpreted using that interpreter.

  3. If no interpreter is available, then a return code value of 1 (one) is presumed for the script, and all other actions defined for that return code are assumed. See the definitions for tagmref_swask , tagmref_swconfig , tagmref_swinstall , tagmref_swremove , and tagmref_swverify .

During the execution of each such control script, the following environment variables are defined for the environment of the control_script:

SW_CATALOG

The value of the installed_software.catalog attribute indicating the location or identification of the catalog relative to the SW_ROOT_DIRECTORY.

SW_CONTROL_DIRECTORY

The directory where the executing script is located.

This directory is readable from within control script execution and is writable from commands within control scripts when the request script is being executed. All control_files are readable by any control script.

SW_CONTROL_TAG

The tag of the script being executed.

This allows the control_script to tell what tag is being executed when the actual script path is defined for more than one tag.

SW_LOCATION

The base directory where the product or fileset will be installed or is already installed.

This is the value of the location attribute.

SW_PATH

A PATH which, at least, contains all utilities defined by the POSIX.2.5

SW_ROOT_DIRECTORY

The installed_software.path attribute of the installed software object within which the software containing this control_file is installed.

This is the directory relative to which all operations with the script are performed.6

SW_SESSION_OPTIONS

The pathname of a file containing the value of every option defined for the software utility being executed, using the options syntax described in Extended Options Syntax .

The option syntax is restricted such that the command prefix is not used, there are no spaces on either side of the = (equal sign), and multiple valued options have the values quoted.

This environment variable allows scripts to retrieve any options and values for this command other than the ones provided explicitly via environment variables. When the file pointed to by SW_SESSION_OPTIONS is made available to request scripts, the targets option contains a list of software_collection_specs for all targets specified for the command. When the file pointed to by SW_SESSION_OPTIONS is made available to other scripts, the targets option contains the single software_collection_spec for the targets on which the script is being executed.

An implementation should ensure that each software_collection_spec contained in the value of the targets option is the same between invocations of commands. This will help ensure that any per-target information stored by the request script can be located by the subsequent scripts.

SW_SOFTWARE_SPEC

The value of the fully-qualified software_spec identifying the software object containing this control script.

In order to allow a control script to know whether it is a new install or an update in order to change its behavior accordingly, the swinstall utility sets the environment variable SW_ANCESTORS to the fully qualified software_specs of the ancestor or ancestors of the fileset that currently are installed.

See Fully-qualified Software_spec .

Control Script Stdout and Stderr
The scripts may send information, particularly about reasons for error conditions to stdout and stderr. The utilities logs stdout and stderr to the logfile of the role executing the script.
Control Script Return Code
The scripts return with a return code of 0 (zero), 1 or 2. Additionally, checkinstall , checkremove , configure , and unconfigure scripts may return with a return code of 3. The return codes 4 through 31 (inclusive) are reserved for future use. The meaning of these return codes is shown in the following table:

Table: Script Return Codes

Return Code Effect of Return Code Status
0 The script executed successfully. The utility will proceed normally. SW_NOTE
1 The script had an error. The utility generates an error event and implement the error procedure defined for this script type. SW_ERROR
2 The script had a warning. The utility will generate a warning event and continue. SW_WARNING
3 The script is forcing a deselection of this product or fileset. The utility will generate a note and skip this product or fileset during any further processing. SW_NOTE
4-31 Reserved.  

All scripts, with the exception of the request script, are non-interactive.

An implementation can define behaviors for additional script return codes. Any such behavior is implementation defined.

Return codes with no behavior defined by either this Software Administration specification or the implementation should be treated using the behavior associated with return code 2.

Asynchronous Events

The following are the set of events generated by the utilities defined in this Software Administration specification. These events are generated during the course of a execution of a utility. See Logging .

The event codes and their numeric values are listed in General Error Events , Session Events , Analysis Phase Events , and Execution Phase Events , inclusive.7

Each event generated also has a severity status associated with it. The event status that can occur for each event is also listed. Event status also has a numeric value, as described in Event Status , General Error Events , Session Events , Analysis Phase Events , and Execution Phase Events . In addition, all numeric values between 0 and 255 (inclusive) are reserved, either for use in this Software Administration specification (as described in the accompanying tables) or for use in future revisions of this Software Administration specification.

Table: Event Status

Status Effect of Event Value
SW_NOTE The operation continues normally 0
SW_ERROR Implementation defined error handling procedure is invoked 1
SW_WARNING The operation continues normally 2

A command will not have an exit code of zero if any SW_ERROR event occurred during the course of a command.

The descriptions in the following tables describe the conditions that lead to this event, and the set of possible event status values for the event. The tables also include "Manager info" and "Target info" that describe the additional information that may be logged for manager and target role event logging respectively. See Logging .

General Error Events lists general source and target role events. The way in which some of these events are generated (if at all) may be different for different implementations.

Table: General Error Events

Event Code Event Status Description Value
SW_ILLEGAL_STATE_TRANSITION SW_ERROR The manager is requesting a phase out of order. Manager info: target. Target info: current phase. 1
SW_BAD_SESSION_CONTEXT SW_ERROR The manager has contacted the wrong target, or this is not a valid manager for this session. Manager info: target. Target info: information about the initiator. 2
SW_ILLEGAL_OPTION SW_ERROR An illegal or unrecognized option was sent. Manager info: target, number of options. Target info: option names and values. 3
SW_ACCESS_DENIED SW_ERROR The user has insufficient privilege to perform the requested operation. Manager info: target. Target info: information about the initiator. 4
SW_MEMORY_ERROR SW_ERROR The target role had a memory allocation error (for example, out of swap). Manager info: target. Target info: reasons for error. 5
SW_RESOURCE_ERROR SW_ERROR The target role had a resource allocation error such as maximum number of processes reached, maximum number of files open, etc. Manager info: target. Target info: reasons for error. 6
SW_INTERNAL_ERROR SW_ERROR The target role had an internal implementation error. Manager info: target. Target info: reasons for error. 7
SW_IO_ERROR SW_ERROR An I/O error occurred while performing this command. Manager info: target. Target info: reasons for error. 8


Session Events lists the source and target role events related to initialization of a session and ending a session. The way in which some of these events are generated (if at all) may be different for different implementations.

Table: Session Events

Event Code Event Status Description Value
SW_AGENT_INITIALIZATION_FAILED SW_ERROR Failed to initialize a target session. Manager info: target. Target info: reasons for error. 10
SW_SERVICE_NOT_AVAILABLE SW_ERROR The target role is not accepting new requests. Manager info: target. Target info: reasons for error. 11
SW_OTHER_SESSIONS_IN_PROGRESS SW_WARNING There are other sessions in progress that may affect the results of this command. Manager info: target, number of sessions. Target info: information about other sessions. 12
SW_SESSION_BEGINS SW_NOTE The command begins on the target. Manager info: target. Target info: information about the initiator of the command. 28
SW_SESSION_ENDS SW_NOTE
SW_WARNING
SW_ERROR
The command ends on the target successfully, with warnings, or with errors. Manager info: target. Target info: none. 29
SW_CONNECTION_LIMIT_EXCEEDED SW_ERROR The limit of source or target role sessions on this host has already been reached. Manager info: target, number of sessions. Target info: number of sessions, limit. 30
SW_SOC_DOES_NOT_EXIST SW_ERROR The requested target or source software collections does not exist. Manager info: target. Target info: reasons for error. 31
SW_SOC_IS_CORRUPT SW_ERROR The software_collection exists, but the information is corrupt. Manager info: target. Target info: reasons for error. 32
SW_SOC_CREATED SW_NOTE The target software_collection did not previously exist and was created. Manager info: target. Target info: none. 34
SW_CONFLICTING_SESSION
    _IN_PROGRESS
SW_ERROR
SW_WARNING
A conflicting session is in progress that will prevent this operation (error), or cause its results to possibly be invalid (warning). Manager info: target. Target info: information about other sessions. 35
SW_SOC_LOCK_FAILURE SW_ERROR Can not set the proper access control to this source or target. Manager info: target. Target info: reasons for error. 36
SW_SOC_IS_READ_ONLY SW_ERROR
SW_NOTE
The software_collection is a read only source for a read source or target (note), or is a target to be modified (error). Manager info: target. Target info: none. 37
SW_SOC_IS_REMOTE SW_ERROR
SW_NOTE
The software_collection is on a remote file system. (Whether note or error is implementation defined). Manager info: target. Target info: none. 38
SW_SOC_INCORRECT_MEDIA_TYPE SW_ERROR The distribution is an incorrect type for the command (for example, a tape for swremove). Manager info: target. Target info: reasons for error. 39
SW_SOC_IS_SERIAL SW_NOTE The distribution has a serial format (for example, a tape). Manager info: target. Target info: none. 40
SW_SOC_INCORRECT_TYPE SW_ERROR The software_collection is of the wrong type (distribution or installed_software) for the operation. Manager info: target. Target info: target type. 41
SW_CANNOT_OPEN_LOGFILE SW_ERROR Cannot open logfile to log the software_collection events. Manager info: target. Target info: reasons for error. 42
SW_SOC_AMBIGUOUS_TYPE SW_ERROR The software collection is inadequately specified for the operation. Manager info: target. Target info: reason for error 49
SW_TERMINATION_DELAYED SW_NOTE The target role is currently analyzing or executing a command and will terminate the session once completed. Manager info: target. Target info: none. 50
SW_CANNOT_INITIATE_REBOOT SW_WARNING The target role failed to initiate the reboot operation of an install command and requires manual reboot. Manager info: target. Target info: reasons for error. 51


Analysis Phase Events lists the source and target role events related to the analysis phase of the commands. Some of these are also related to the execution phase of the commands.

Table: Analysis Phase Events

Event Code Event Status Description Value
SW_ANALYSIS_BEGINS SW_NOTE The analysis phase begins on the target. Manager info: target. Target info: none. 52
SW_ANALYSIS_ENDS SW_NOTE
SW_WARNING
SW_ERROR
The analysis phase ends on the target. The analysis may have succeeded, had warnings, and/or errors. Manager info: target. Target info: none. 53
SW_EXREQUISITE_EXCLUDE SW_NOTE One or more filesets were excluded automatically as the software identified as exrequisites was also specified to be selected. Manager info: target, number of filesets. Target info: software_specs 56
SW_CHECK_SCRIPT_EXCLUDE SW_NOTE One or more checkinstall or checkremove scripts have caused the software to be unselected and excluded from further processsing. Manager info: target, number of filesets. Target info: software_specs 57
SW_CONFIGURE_EXCLUDE SW_NOTE One or more configure or unconfigure scripts have caused the software to be unselected and excluded from further processsing. Manager info: target, number of filesets. Target info: software_specs 58
SW_SELECTION_IS_CORRUPT SW_ERROR The software selection was found, but its state was corrupt or transient. Manager info: target, number of selections Target info: software_specs 59
SW_SOURCE_ACCESS_ERROR SW_ERROR Failure contacting or retrieving information from the source. Manager info: target. Target info: reasons for error. 60
SW_SOURCE_NOT_FIRST_MEDIA SW_ERROR The source does not have a media number of 1 (needed for retrieval of the INDEX). Manager info: target, current media number. Target info: current media number. 61
SW_SELECTION_NOT_FOUND SW_ERROR
SW_NOTE
One or more software selections can not be found. This is an error for install or copy; otherwise, a note. Manager info: target, number of selections. Target info: software_specs 62
SW_SELECTION_NOT
    _FOUND_RELATED
SW_ERROR
SW_NOTE
One or more software selections can not be found as specified, but another version exists. This is an error for install or copy; otherwise, a note. Manager info: target, number of selections. Target info: software_specs 63
SW_SELECTION_NOT
    _FOUND_AMBIG
SW_ERROR One or more software selections can not be unambiguously determined. Manager info: target, number of selections. Target info: software_specs 64
SW_FILESYSTEMS_NOT_MOUNTED SW_ERROR
SW_WARNING
One or more file systems on the target are not mounted. Manager info: target, number of file systems. Target info: file system names. 65
SW_FILESYSTEMS_MORE_MOUNTED SW_WARNING One or more file systems mounted are not in file system table. Manager info: target, number of file systems. Target info: file system names. 66
SW_HIGHER_REVISION_INSTALLED SW_ERROR
SW_WARNING
One or more filesets have a higher revision already installed. Whether error or warning is controlled by allow_downdate option. Manager info: target, number of filesets. Target info: software_specs 67
SW_NEW_MULTIPLE_VERSION SW_ERROR
SW_NOTE
One or more products would create a new version in an installation. Whether error or warning is controlled by allow_multiple_versions option. Manager info: target, number of products. Target info: software_specs 68
SW_EXISTING_MULTIPLE_VERSION SW_ERROR
SW_WARNING
SW_NOTE
The command is operating on an existing multiple version of one or more products. If trying to install two versions into one location, generate an event. Warning or note controlled by allow_multiple_versions option. Manager info: target, number of products. Target info: software_specs 69
SW_DEPENDENCY_NOT_MET SW_ERROR
SW_WARNING
One or more dependencies can not be met. Whether error or warning is controlled by enforce_dependencies option. Manager info: target, number of filesets. Target info: software_specs, dependency_specs 70
SW_NOT_COMPATIBLE SW_ERROR
SW_WARNING
One or more products are incompatible for this target. Whether error or warning is controlled by allow_incompatible option. Manager info: target, number of products. Target info: software_specs 71
SW_CHECK_SCRIPT_WARNING SW_WARNING One or more checkinstall, checkremove or verify scripts had a warning. Manager info: target, number of filesets. Target info: software_specs 72
SW_CHECK_SCRIPT_ERROR SW_ERROR One or more checkinstall, checkremove or verify scripts failed. Manager info: target, number of filesets. Target info: software_specs 73
SW_DSA_INTO_MINFREE SW_ERROR
SW_WARNING
Disk space analysis is over the minimum free limit, but not the overall limit on the target. Whether error or warning is controlled by enforce_dsa option. Manager info: target, number of file systems. Target info: file system names, amount over the minimum free. 74
SW_DSA_OVER_LIMIT SW_ERROR
SW_WARNING
Disk space analysis is over the absolute limit. Whether error or warning is controlled by enforce_dsa option. Manager info: target, number of file systems. Target info: file system names, amount over the limit. 75
SW_DSA_FAILED_TO_RUN SW_ERROR
SW_WARNING
Disk space analysis had an internal error and failed to run. Whether error or warning is controlled by enforce_dsa option. Manager info: target, number of filesets. Target info: software_specs 76
SW_SAME_REVISION_INSTALLED SW_NOTE One or more filesets have the same revision and are being reinstalled because reinstalltrue or recopytrue. Manager info: target, number of filesets. Target info: software_specs 77
SW_ALREADY_CONFIGURED SW_NOTE One or more filesets are already configured Whether they are reconfigured is controlled by reconfigure option. Manager info: target, number of filesets. Target info: software_specs 78
SW_SKIPPED_PRODUCT_ERROR SW_NOTE One or more filesets will be skipped because of another error within their product. (Error handling is implementation defined). Manager info: target, number of filesets. Target info: software_specs 79
SW_SKIPPED_GLOBAL_ERROR SW_NOTE One or more filesets will be skipped because of a global error (such as disk space analysis failure) within the analyze phase. (Error handling is implementation defined). Manager info: target, number of filesets. Target info: software_specs 80
SW_FILE_IS_REMOTE SW_WARNING
SW_NOTE
One or more files would be created or removed on a remote file system. (Policy for loading remote files is implementation defined). Manager info: target, number of files. Target info: file paths. 81
SW_FILE_IS_READ_ONLY SW_WARNING One or more files will not be attempted to be created or removed on a read only file system. Manager info: target, number of files. Target info: file paths. 82
SW_FILE_NOT_REMOVABLE SW_WARNING One or more files could not be removed (for example, text busy, or non-empty directories). Manager info: target, number of files. Target info: file paths. 83
SW_FILE_WARNING SW_WARNING One or more files had warnings in analysis or execution. Manager info: target, number of files. Target info: file paths. 84
SW_FILE_ERROR SW_ERROR One or more files had errors in analysis or execution. Manager info: target, number of files. Target info: file paths. 85
SW_NOT_LOCATABLE SW_WARNING
SW_ERROR
A fileset is not locatable. Controlled by the enforce_locatable option. Manager info: target, number of filesets. Target info: software_specs 86
SW_SAME_REVISION_SKIPPED SW_NOTE One or more filesets have the same revision and are being skipped because reinstallfalse or recopyfalse. Manager info: target, number of filesets. Target info: software_specs 87


Execution Phase Events lists the error, warning and notes for target role events related to the execution phase.

Table: Execution Phase Events

Event Code Event Status Description Value
SW_EXECUTION_BEGINS SW_NOTE The execution phase begins on the target. Manager info: target. Target info: none. 88
SW_EXECUTION_ENDS SW_NOTE
SW_WARNING
SW_ERROR
The execution phase ends on the target. Manager info: target. Target info: none. 89
SW_SELECTION_SKIPPED
    _IN_ANALYSIS
SW_NOTE One or more selections will not be included for execution because they were determined to be skipped in analysis. Manager info: target, number of filesets. Target info: software_specs 90
SW_SELECTION_NOT_ANALYZED SW_ERROR One or more software selections were found, but were not analyzed. Manager info: target, number of filesets. Target info: software_specs 91
SW_WRONG_MEDIA_SET SW_ERROR The source media current being used is not the same as that used for analysis. Manager info: target. Target info: information about current media and needed media. 92
SW_NEED_MEDIA_CHANGE SW_NOTE The target needs the next media. (Interactive support for media change is implementation defined). Manager info: target, needed media sequence number. Target info: needed media sequence number. 93
SW_CURRENT_MEDIA SW_NOTE The current media sequence number for the target Manager info: target, current media sequence number. Target info: current media sequence number. 94
SW_PRE_SCRIPT_WARNING SW_WARNING One or more preinstall , preremove , unpreinstall , or fix scripts had a warning. Manager info: target, number of scripts. Target info: software_spec , script tag 95
SW_PRE_SCRIPT_ERROR SW_WARNING
SW_ERROR
One or more preinstall , preremove , unpreinstall , or fix scripts failed. Manager info: target, number of scripts. Target info: software_spec , script tag 96
SW_FILESET_WARNING SW_WARNING One or more filesets had a warning. Manager info: target, number of filesets. Target info: software_specs 97
SW_FILESET_ERROR SW_ERROR One or more filesets had an error. Manager info: target, number of filesets. Target info: software_spec s 98
SW_POST_SCRIPT_WARNING SW_WARNING One or more postinstall ,
postremove , or
unpostinstall scripts had a warning. Manager info: target, number of filesets. Target info: software_specs
99
SW_POST_SCRIPT_ERROR SW_WARNING
SW_ERROR
One or more postinstall , postremove , or unpostinstall scripts failed. Manager info: target, number of filesets. Target info: software_specs 100
SW_POSTKERNEL_WARNING SW_WARNING The postkernel kernel build script had a warning. Manager info: target. Target info: reasons for error. 101
SW_POSTKERNEL_ERROR SW_ERROR The kernel failed to build. Manager info: target. Target info: reasons for error. 102
SW_CONFIGURE_WARNING SW_WARNING One or more configure or unconfigure scripts had a warning. Manager info: target, number of scripts. Target info: software_specs, script tag 103
SW_CONFIGURE_ERROR SW_WARNING
SW_ERROR
One or more configure or unconfigure scripts failed. Manager info: target, number of scripts. Target info: software_specs, script tags 104
SW_DATABASE_UPDATE_ERROR SW_ERROR An update to the catalog information for installed_software or distributions failed. Manager info: target. Target info: reasons for error. 105
SW_REQUEST_WARNING SW_WARNING One or more request scripts had a warning. Manager info: software_specs 106
SW_REQUEST_ERROR SW_ERROR One or more request scripts failed. Manager info: software_specs 107
SW_COMPRESSION_FAILURE SW_ERROR A file could not be compressed or uncompressed. Manager info: target. Target info: filepath. 112
SW_FILE_NOT_FOUND SW_ERROR File is missing from the source or target software_collection. Manager info: target, number of files. Target info: file path. 113
SW_FILESET_BEGINS SW_NOTE The execution phase of a fileset begins. Manager info: target. Target info: software_spec 117
SW_CONTROL_SCRIPT_BEGINS SW_NOTE The execution of a control script begins. Manager info: target. Target info: software_spec , control script tag 118
SW_FILE_BEGINS SW_NOTE The execution phase of file begins. Manager info: target. Target info: file path. 119

Stdout

Events with a status of SW_NOTE will, if permitted by the value verbose, be directed to stdout. Manager role events will, if permitted by the value verbose, be directed to stdout. Nothing is written to stdout if verbose0 (zero). The writing of any target role events to stdout is undefined.

Stderr

If any events with a status of SW_ERROR or SW_WARNING occur on a target role, this information is communicated to the management role. In addition, at least a single message for that target will, if permitted by the value verbose, be directed to the stderr of the management role. Nothing is written to stderr if verbose0 (zero).

The sending of any additional messages to stderr of the management role is undefined.

See verbose in section Extended Options .

Logging

The management role and target role each log events. The way in which logging is implemented, including the location of the logfiles, is implementation defined.

Which messages, if any, are placed in the source role logfile is undefined.

All implementations support the values 0 (zero), 1 (one) and 2.. If loglevel0, nothing is written to log files. The target role logs all events, except file level events, when loglevel1. The target role redirects, to the logfile, stderr and stdout from control scripts when loglevel1. When loglevel2, the target role logs file level events. For values which are non-negative integers, an increase in loglevel does not decrease the information logged for a given role. All other behavior regarding logging is undefined.

See loglevel in section Extended Options .

Extended Description

See the individual utility sections for the complete extended descriptions of each task. This section lists the steps common to the utilities.

There are three phases in the utilities. Targets may be processed in any order or in parallel.

  1. Selection phase
    When the user specifications are resolved, including source, target, and software selections.

  2. Analysis phase
    When the utility attempts to discover conditions which may cause failure when operating on the selected software.

  3. Execution phase
    When the actual operations on the software objects take place.

When a utility initiates a session on a target, generate an event.
(SW_NOTE: SW_SESSION_BEGINS)

When the session completes, generate an event.
(SW_NOTE: SW_SESSION_ENDS)

Selection Phase

This section summarizes the common tasks in the selection phase. Errors and warnings are listed along with the tasks.

Starting a Session

On invocation, each command processes options as defined in Precedence for Option Specification .

The command exits if the user does not have appropriate privilege. Since implementation of the security scheme is unspecified within this Software Administration specification, appropriate privilege is implementation defined. An implementation may generate the following events at any point in the execution of the command if they are applicable to that implementation:

(SW_ERROR: SW_ACCESS_DENIED)
(SW_ERROR: SW_ILLEGAL_OPTION)
(SW_ERROR: SW_MEMORY_ERROR)
(SW_ERROR: SW_RESOURCE_ERROR)
(SW_ERROR: SW_INTERNAL_ERROR)
(SW_ERROR: SW_TERMINATION_DELAYED)
(SW_ERROR: SW_IO_ERROR)
Specifying Targets
A target is specified using the syntax in Source and Target Specification and Logic . Each target passes the following validation checks. If any of these checks fail, the command invokes the implementation defined error handling procedure.

Specifying the Source
This section only applies to swcopy and swinstall. The source contains software organized in the software packaging layout. A target can be specified using the syntax in Source and Target Specification and Logic .

If source is specified, then it is resolved in the context of the management role. If source is not specified, then a default value is supplied as defined in Precedence for Option Specification .

A source must satisfy the following validation checks:

Software Selections
Software selections can be specified on the command line or in an input file using the syntax in Software Specification and Logic .

Analysis Phase

This section summarizes the common operations and events in the analysis phase. The analysis phase occurs before the execution phase, and involves executing checks to determine whether or not the execution should be attempted.

When the analysis phase begins, generate an event
(SW_NOTE: SW_ANALYSIS_BEGINS)

To begin the analysis phase, the management role (the host on which the utility was invoked) communicates the selection information to each target in the target list. The target role accesses the source (for swinstall or swcopy) or target (for other utilities) to get the product catalog information for the software selections. The product catalog information includes control script information in the control_files attribute of filesets within each product.

See each utility section for the analysis operations specific to each utility. When the analysis phase ends, generate an event.
(SW_NOTE: SW_ANALYSIS_ENDS)

Execution Phase

This section summarizes the common operations and events in the execution phase.

When the execution phase begins, generate an event.
(SW_NOTE: SW_EXECUTION_BEGINS)

The execution phase proceeds through the steps defined for each utility. The following events are common to all utilities.

See each utility section for the execution operations specific to each utility. When the execution phase completes, generate an event.
(SW_NOTE: SW_EXECUTION_ENDS)

Fileset State Transitions
A conforming implementation must maintain the state attribute of each fileset to identify the condition and validity of that package. A conforming implementation must use these and only these states as valid values of the filesetstate attribute.

configured

Indicates the fileset in an installed_software object has been configured.

This state applies to filesets in installed_software objects.

installed

Indicates that the specified fileset has been installed successfully.

corrupt

Indicates that the most recent attempt to handle the fileset was not successful and any recovery actions that were attempted were similarly unsuccessful.

Software can transition from this state via the swinstall, swcopy, or swremove utilities. Other implementation defined methods may also exist for transitioning from this state.

This state applies to filesets in distributions and installed_software objects.

removed

This state indicates that the files for the fileset has been removed but the information remains.

The default behavior when removing software with swremove is to also remove its information (metadata) from the catalog. An implementation may define a means for removing software, but maintaining the catalog information. The catalog information can be separately removed with the swmodify utility.

This state applies to filesets in distributions and installed_software objects.

available

Indicates the fileset is present in the distribution and may be operated on (copied, installed, etc.) using the appropriate utilities.

This state applies to filesets in a distribution.

transient

Indicates that the fileset is currently being acted on by one of the utilities that modify software files, thus the state of the software is not well defined.

This state should be replaced by another before the utility completes. Presence of this state in the software_collection when no utility is running indicates that a utility was previously interrupted (power failure, kill, etc) and was not able to record a final state indication into the software_collection catalog. In such case, the implementation defined recovery procedures can be used to restore the product to a another state.

This state applies to filesets in distributions and installed_software objects.

Exit Status

The utility returns one of the following exit codes:

Table: Return Codes

Return Code Definition
0 The utility was successful on all targets
1 The utility failed on all targets
2 The utility failed on some targets

The exit status for the swpackage utility is different since it is not a distributed utility.

Consequences of Errors

Utilities can operate on multiple software objects contained in multiple targets. Whether an error impacts a particular software object, all software objects in the target, or all targets, is implementation defined. One exception to this is the minimum error recovery procedure described in swinstall , which describes fileset level recovery during install.

Error Conditions

The conditions leading to errors are described in Asynchronous Events , and Extended Description .


Footnotes

1.
For examples of the use of specifications in this section, see Sample File Coding .

2.
As defined in the syntax for ver_item , this comparison is required for revision only and any other comparison is undefined.

3.
Note that leading zeros are acceptable in such segments.

4.
Since failure prior to executing the preinstall script should have no side effects, a failure implies that the unpreinstall script requires execution.

5.
POSIX.2 requires and defines the C function confstr() that obtains such a PATH.

6.
For example, if this normally has a value of /, but if a proxy install is done to a target directory /mnt/test/, this will have the value of /mnt/test/.

7.
Not all events are generated by each utility. For example, events related to script execution only apply to swinstall, swask, swremove and swverify. The specific events generated by each utility are defined in the section for that utility.


[??] Some characters or strings that appear in the printed document are not easily representable using HTML.


Why not acquire a nicely bound hard copy?
Click here to return to the publication details or order a copy of this publication.

Contents Next section Index