Common Definition for Utilities

Synopsis

<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

Options

-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

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

Operands

Software Specification and Logic

%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,² 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),³ 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

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

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

%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

Extended Options

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,⁴ 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

%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:

• command
  A keyword prefixed by the command name applies to that utility only.

  If no prefix exists, then the keyword applies to all the utilities that support it.

• keyword
  Names the option or operand being defined, for example, allow_incompatible for swinstall, and verbose for all the utilities.

  The allowable characters for a keyword are as defined in the filename character set, plus the - (hyphen) character.

• value
  Assigns the value to the keyword.

  All extended options are single valued except those that contain lists of software_specs or software_collection_specs . Quoting of strings and escaping of characters is handled as specified in POSIX.2.

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

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:

• If both keyword and command.keyword exist in the set of defaults or options files for this level, the command uses the latter, more specific, definition.

• All values for software and targets options from all levels are all included in the resulting software_selections and target_selections for the command.

• For options besides software and targets, the behavior when multiple or conflicting specifications are made is undefined. This rule applies to options such as s source where implementations may choose to assign a logical interpretation to multiple source specification. The same rule applies to options that are mutually exclusive.

Input Files

Access and Concurrency Control

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

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

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.⁵

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.⁶

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

Control Script Return Code

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 event codes and their numeric values are listed in General Error Events , Session Events , Analysis Phase Events , and Execution Phase Events , inclusive.⁷

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.

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.

Stdout

Stderr

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

See verbose in section Extended Options .

Logging

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

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

• If the target role was unable to initialize the session on the target host, generate an event.
  (SW_ERROR: SW_AGENT_INITIALIZATION_FAILED)

• If administrative access is denied by the target role on the target, generate an event.
  (SW_ERROR: SW_ACCESS_DENIED)

• Except for swinstall, swcopy, and swpackage, if the target does not exist on a host, an error is generated:
  (SW_ERROR: SW_SOC_DOES_NOT_EXIST)

• For swinstall, swcopy, and swpackage, if the target directory does not exist on a host, it is created with default attributes.
  (SW_NOTE: SW_SOC_CREATED)

• If the target is corrupt, generate an event.
  (SW_ERROR: SW_SOC_IS_CORRUPT)

• If the target is the wrong type (installed_software or distribution) for the target type the user specified (with a -r or -d option respectively), generate an event.
  (SW_ERROR: SW_SOC_INCORRECT_TYPE)

  If both a distribution object and an installed_software object exist at the location specified in the target, and neither the -d nor the -r option is specified, generate an event.
  (SW_ERROR: SW_SOC_AMBIGUOUS_TYPE)
  

• If the target is a serial distribution, generate an event.
  (SW_NOTE: SW_SOC_IS_SERIAL)

  If the command is swcopy or swpackage, a serial distribution is overwritten by default. If the command is swremove, swmodify, or swverify, and the implementation does not support these on a serial distribution, an event is generated.
  (SW_ERROR: SW_SOC_INCORRECT_MEDIA_TYPE)

• If the target is not able to open the implementation defined logfile, generate an event.
  (SW_ERROR: SW_CANNOT_OPEN_LOGFILE)

• If the operation needs to modify the target, and it is on a read-only media or file system, generate an event.
  (SW_ERROR: SW_SOC_IS_READ_ONLY)

• An implementation may generate the following events, if they are applicable to that implementation, when validating a target:
  (SW_ERROR: SW_SERVICE_NOT_AVAILABLE)
  (SW_WARNING: SW_OTHER_SESSIONS_IN_PROGRESS)
  (SW_ERROR: SW_CONNECTION_LIMIT_EXCEEDED)
  (SW_NOTE: SW_SOC_IS_REMOTE)
  (SW_ERROR: SW_FILESYSTEMS_NOT_MOUNTED)
  (SW_ERROR: SW_FILESYSTEMS_MORE_MOUNTED)

Specifying the Source

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:

• Verify that the source exists, and may be accessed
  (SW_ERROR: SW_SOURCE_ACCESS_ERROR).

• If administrative access is denied by the source role for that source, generate an event.
  (SW_ERROR: SW_ACCESS_DENIED)

• Obtain information on what software is available from the source. If the information cannot be retrieved, or if an problem occurs while processing it, generate an event.
  (SW_ERROR: SW_SOURCE_ACCESS_ERROR)

• If the source is a serial media, and the mediasequence_number is not 1, then generate an event. (Only the first media has the catalog information on it).
  (SW_ERROR: SW_SOURCE_NOT_FIRST_MEDIA)

Software Selections

Analysis Phase

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.

• An implementation may generate any of the following events, if they are applicable to that implementation, when attempting the analysis or execution phase.
  (SW_ERROR: SW_AGENT_INITIALIZATION_FAILED)
  (SW_ERROR: SW_ILLEGAL_STATE_TRANSITION)
  (SW_ERROR: SW_BAD_SESSION_CONTEXT)

• If the target role cannot access the source, generate an event.
  (SW_ERROR: SW_SOURCE_ACCESS_ERROR)

• If an implementation supports access control for particular operations for particular software objects, and if access is denied for any software object, generate an event.
  (SW_ERROR: SW_ACCESS_DENIED)

• If a fileset has an error for which there is not a more specific event defined, generate the generic event.
  (SW_ERROR: SW_FILESET_ERROR)

• If a fileset has a warning for which there is not a more specific event defined, generate the generic event.
  (SW_WARNING: SW_FILESET_WARNING)

• An implementation may generate the following events as applicable to the error handling procedures for that implementation:
  (SW_NOTE: SW_SKIPPED_PRODUCT_ERROR)
  (SW_NOTE: SW_SKIPPED_GLOBAL_ERROR)
  (SW_WARNING: SW_FILE_IS_READ_ONLY)

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

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.

• When the execution phase executes a script, generate an event.
  (SW_NOTE: SW_CONTROL_SCRIPT_BEGINS)

• When the execution phase begins the key operation on a fileset (such as loading or removing), generate an event.
  (SW_NOTE: SW_FILESET_BEGINS)

• When the execution phase begins the key operation on a file (such as loading or removing), generate an event.
  (SW_NOTE: SW_FILE_BEGINS)

• If at any time there is an error rebuilding any catalog files, generate an event.
  (SW_ERROR: SW_DATABASE_UPDATE_ERROR)

• If a fileset has an error for which there is not a more specific event defined, generate the generic event.
  (SW_ERROR: SW_FILESET_ERROR)

• If a fileset has a warning for which there is not a more specific event defined, generate the generic event.
  (SW_WARNING: SW_FILESET_WARNING)

• For swinstall and swcopy from a distribution that spans multiple media, an implementation may generate the following events to convey needed media change information. An implementation may, but need not, provide such support for other utilities.
  (SW_ERROR: SW_WRONG_MEDIA_SET)
  (SW_NOTE: SW_NEED_MEDIA_CHANGE)
  (SW_NOTE: SW_CURRENT_MEDIA)

• An implementation may generate the following events for software that will not be executed due to analysis results for that software.
  (SW_NOTE: SW_SELECTION_SKIPPED_IN_ANALYSIS)
  (SW_ERROR: SW_SELECTION_NOT_ANALYZED)

• The default behavior for filesets in the removed state is the same as for filesets that are non-existent. Implementations that support the removed state should define extensions to the 1387.2 utilities providing operations on removed filesets.

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

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 exit status for the swpackage utility is different since it is not a distributed utility.

Consequences of Errors

Error Conditions

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.