Software Packaging Layout

This section describes the software packaging layout. The software packaging layout consists of:

1. The directory structure consisting of these major components:

   • The exported catalog structure containing software information including software definition files and customize scripts used by the install/update and copy utilities

   • The file storage structure that contains the actual software files for each fileset

2. the software definition file formats and the objects and attributes they contain, INDEX for software definitions and INFO for file and control_file definitions (used by all the utilities defined in this Software Administration specification), the PSF for product specification (used by swpackage), and the space file (used by disk space analysis in install).

3. The serial format of the layout containing an archive of files in the directory structure.

   This ordering of directories and files also applies to distributions on a set of hierarchical file systems which span multiple media.

Thus, two distinct (but related) formats for the software packaging layout are supported by this Software Administration specification:

• A directory structure format which resides within a POSIX.1 hierarchical file system (disk, CD-ROM, etc.)

• A bit stream serial format which resides within a POSIX.1 extended cpio or extended tar archive

A conformant implementation does not contain any other files or directories besides those explicitly entered in the distribution catalog. However, it can contain other files and directories besides those belonging to the distribution.

Directory Structure

This Software Administration specification defines a single directory structure for directory and serial distributions. The software packaging layout can be stored in two forms:

• A direct access file system as described in this section

• A serial access extended cpio or extended tar archive as described in POSIX.1

The same structure offers optimal load performance for serial distributions while providing a simple structure for directory distributions. This structure applies to each media if the distribution spans multiple media.

The structure supports multiple versions of a product contained within a single distribution, where versions are distinguished by a unique combination the product tag, revision, architecture, and vendor_tag attributes.

Example of Software Packaging Layout shows the directory structure of a software packaging layout located under a directory path:

 

Table: Example of Software Packaging Layout

The directory structure for the software packaging layout is divided into two areas:

• The exported catalog structure, consisting of control directories containing the software definition files that describe the products contained in the distribution, as well as the software control_files

• The software file storage structure, consisting of the product and fileset storage directories, under which the actual software files for each fileset are located

Exported Catalog Structure

INDEX File

• catalog/INDEX

  This INDEX file contains the definition of all software objects in the distribution.

Distribution Files

• <attribute>

  A distribution attribute can be stored as a separate file, the file name of which can be the name of the attribute.

Product Catalog

Product Control Files

• <attribute>

  A product attribute can be stored as a separate file, the file name of which can be the name of the attribute.
  

• INFO

  Contains the definitions for the control_file objects contained within the product.

• checkinstall
  preinstall
  ...
  postremove

  The vendor-supplied control scripts for the product.

• <control_file>

  All other vendor-defined control_files for this product.

Fileset Control Files

• <attribute>

  A fileset attribute can be stored as a separate file, the filename of which can be the name of the attribute.

• INFO
  Contains the definitions for the control_file and file objects contained within the fileset.

• checkinstall
  preinstall
  ...
  postremove

  The vendor-supplied control scripts for the fileset.

• <control_file>

  All other vendor-defined control_files for this fileset.

File Storage Structure

The files of each fileset are store in a directory with the name <fileset_control_directory> which is itself in a directory called <product_control_directory>.

Each regular file (ones for which file.type is f) is stored in a location defined by appending the file.path attribute to the path of the fileset file storage directory. This may require the creation of additional directories. Other file types (directories, except as needed to store files, hard links and symbolic links) are not required to exist in the distribution. The POSIX.1 file permissions for files in the file storage area are undefined.

Control Directory Names

1. Length of the tag attribute exceeds {POSIX_PATH_MAX} of the system where the distribution resides.

2. Name collision with an existing product control directory.

   Given that multiple versions of a product may be contained in the same distribution, collisions from product control directories named by the tag attribute are common.

These conditions are met by defining a control_directory attribute for each product and fileset that is unique within the distribution. The attribute uses the syntax:

%token          FILENAME_CHARACTER_STRING /* as defined in 2.2.2.37  */

%start  control_directory
%%

control_directory       : tag_part
                        | tag_part "."  instance_id_part
                        ;

tag_part                : FILENAME_CHARACTER_STRING
                        ;

instance_id_part        : FILENAME_CHARACTER_STRING
                        ;

The tag_part may be the product or fileset tag attribute, truncated as necessary to meet any filename length restrictions of the operating system.

The instance_id_part is a string that, when added after the "." (period), defines a control_directory which, for products, is unique within the distribution and, for filesets, is unique within the product. For products, this instance_id_part may be the instance_id of the product if that instance_id was generated considering other products tag_parts in addition to tag attributes.

Software Definition File Format

• The INDEX file contains the definition of distribution or installed_software objects as well as the software objects contained within those software_collections. The information in this file is primarily used in selection phases of the utilities.

• The INFO file contains the definition of the software files and control_files for a product or fileset within a distribution or installed_software object. The information in this file is primarily used in analysis and execution phases of the utilities.

• The PSF (product specification file) also contains the definition of distribution attributes, software objects, and the software files and control_files for the product and fileset software objects. This file is created by the software vendor and used by the packaging tool to create the distribution, represented by the INDEX and INFO files, in the software packaging layout.

  The PSF supports the same syntax as the INDEX and INFO files. Additional syntactic constructs are supported for specifying files and control_files. This file is used in selection, analysis and packaging Phases of the swpackage command.

Additionally, there is a space file that is created by the software vendor for additional disk space needed for a product or fileset. This file is used in analysis phase of the swinstall command to account for additional disk space required.

Software Definition File Syntax

The software specification file syntax is as follows.¹

%token          FILENAME_CHARACTER_STRING /* as defined in Glossary */
%token          NEWLINE_STRING            /* as defined in Glossary */
%token          PATHNAME_CHARACTER_STRING /* as defined in Glossary */
%token          SHELL_TOKEN_STRING        /* as defined in Glossary */
%token          WHITE_SPACE_STRING        /* as defined in Glossary */


%start  software_definition_file
%%


software_definition_file : INDEX
                         | INFO
                         | PSF
                         ;

INDEX                    : soc_definition
                           soc_contents
                         ;

INFO                     : info_contents
                         ;

PSF                      : distribution_definition
                           soc_contents
                         ;


media                    : /* empty */
                         | media_definition
                         ;

vendors                  : /* empty */
                         | vendors NEWLINE_STRING vendor_definition
                         | vendor_definition
                         ;


bundles                  : /* empty */
                         | bundles NEWLINE_STRING bundle_definition
                         | bundle_definition
                         ;

products                 : /* empty */
                         | products NEWLINE_STRING product_specification
                         | product_specification
                         ;

product_specification    : product_definition
                           product_contents
                         ;

subproducts              : /* empty */
                         | subproducts NEWLINE_STRING subproduct_definition
                         | subproduct_definition
                         ;

filesets                 : filesets NEWLINE_STRING fileset_specification
                         | fileset_specification
                         ;

fileset_specification    : fileset_definition
                           fileset_contents
                           /* fileset contents not valid in INDEX files */
                         ;

control_files            : /* empty */
                         | control_files NEWLINE_STRING control_file_definition
                         | control_file_definition
                         ;

files                    : /* empty */
                         | files NEWLINE_STRING file_definition
                         | file_definition
                         ;

fileset_contents         : fileset_contents NEWLINE_STRING fileset_content_items
                         | fileset_content_items
                         ;

fileset_content_items    : control_files
                         | files
                         ;

info_contents            : info_contents NEWLINE_STRING info_content_items
                         | info_content_items
                         ;

info_content_items       : control_files
                         | files
                         ;

product_contents         : product_contents NEWLINE_STRING product_content_items
                         | product_content_items
                         ;

product_content_items    : control_files
                           /* control_files not valid in INDEX files */
                         | subproducts
                         | filesets
                         ;

soc_contents             : soc_contents NEWLINE_STRING soc_content_items
                         | soc_content_items
                         ;

soc_content_items        : vendors
                         | bundles
                         | products
                         ;

soc_definition           : distribution_definition
                         | installed_software_definition
                         ;

distribution_definition  : software_definition
                           media
                         ;

media_definition         : software_definition
                         ;

installed_software_definition : software_definition
                              ;

vendor_definition        : software_definition
                         ;

bundle_definition        : software_definition
                         ;

product_definition       : software_definition
                         ;

subproduct_definition    : software_definition
                         ;

fileset_definition       : software_definition
                         ;

control_file_definition  : software_definition
                         | extended_definition
                           /* extended_definition only valid in PSF files */
                         ;

file_definition          : software_definition
                         | extended_definition
                           /* extended_definition only valid in PSF files */
                         ;

software_definition      : object_keyword NEWLINE_STRING
                           attribute_value_list
                         ;

attribute_value_list     : /* empty */
                         | attribute_value_list attribute_definition NEWLINE_STRING
                         | attribute_definition NEWLINE_STRING
                         ;

attribute_definition     : attribute_keyword WHITE_SPACE_STRING attribute_value
                         ;

object_keyword           : FILENAME_CHARACTER_STRING
                         ;

attribute_keyword        : FILENAME_CHARACTER_STRING
                         ;

extended_definition      : extended_keyword WHITE_SPACE_STRING attribute_value
                         ;

extended_keyword         : FILENAME_CHARACTER_STRING
                         ;

attribute_value          : attribute_value WHITE_SPACE_STRING single_value
                         | single_value
                         | '<' WHITE_SPACE_STRING PATHNAME_CHARACTER_STRING
                         | '<' PATHNAME_CHARACTER_STRING
                         ;

single_value             : SHELL_TOKEN_STRING
                         ;

The following syntax rules are applicable to software definition files:

1. All keywords and values are represented as character strings.

2. Each keyword is located on a separate line. Keywords can be preceded by white space (tab, space). White space separates the keyword from the value.

3. Comments can be placed on a line by themselves or after the keyword-value syntax. They are designated by preceding them with the # (pound) character. The way in which comments are used in INDEX and INFO is undefined

4. All object keywords have no values. All attribute keywords have one or more values.

5. An attribute value ends on the same line as the keyword with one exception. Attribute values can span lines if and only if the value is prefixed and suffixed with the " (double quote) character.

6. When an attribute value begins with < (less than), the remainder of the string value is interpreted as a filename whose contents will be used as a quoted string value for the attribute. For INDEX files, the filename is a path relative to the control directory for that distribution, product, or fileset. For PSF files, the filename is a path to a file on the host that contains the file.

7. The use of " (double quote) is not required when defining a single line string value that contains embedded white space. Trailing white space is removed; embedded white space is used. The quotes can be used.

8. The " (double quote), # (pound), and \ (backslash) characters can be included in multi-line string values by "escaping" them with \ (backslash).

9. The order of attributes is not significant, except that the layout_version is the first attribute defined in an INDEX file for a distribution or installed_software object.

Keyword and Attribute Semantics

1. The object keywords distribution, installed_software, media, category, vendor, bundle, product, subproduct, fileset, control_file, and file each define a new object of that type. The keywords distribution, installed_software, product, and fileset also define nested blocks that contain the objects describing the software hierarchy.

2. If an attribute is not supplied, then its default value is used, unless no default value is permitted.

3. Attributes that have boolean permitted values are described by the strings true and false .

4. Attributes that have an enumerated set of permitted values are described by one of the enumerated values. Enumerated values do not contain spaces and are case sensitive. In addition, abbreviations of the string are not allowed. For example, conf is not equivalent to configured .

5. For attributes whose values are integer character strings, the default value is used if the attribute is not supplied. If the first two characters of an integer character string are 0x (zero followed by a lowercase "x"), then the value is interpreted as hexadecimal. Otherwise, if the first character of an integer character string is 0 (zero), then the value is interpreted as octal. Attribute values denoting time are integer character strings that signify seconds since the Epoch.

6. Attributes whose permitted values are lists of tags or software_specs can be described either by one or more repeating keywords, each listing one or more tags or software_spec s separated by white space (for example, for subproduct.contents or fileset.prerequisites), or by blocks of object fragments (for example, product, fileset, and file definitions).

   The former is used when the hierarchy is defined by reference, and the latter when the hierarchy is defined by containment. For example, subproducts and filesets are contained within products, but filesets are referenced by subproducts.

7. Attributes that have permitted values of software_pattern_matching_string are software pattern matching strings as described in the Glossary. For all product attributes related to the uname structure (as defined in POSIX.1, an empty string value is treated as equivalent to * (asterisk), implying a universal match.

Vendor Defined Keywords and Attributes

The value associated with any keyword is processed as an attribute_value (see Software Definition File Syntax ) and thus can be continued across multiple input lines or can reference a file containing the value for the keyword.

Implementations that make use of keywords beyond those described in this Software Administration specification take actions they believe appropriate for those keywords. The handling of any keywords which are both not defined by this Software Administration specification, and still recognized by an implementation, is undefined.

Distribution Definition

 

distribution
    layout_version         layout_version
    path                   path
    dfiles                 dfiles
    pfiles                 pfiles
    uuid                   uuid

INDEX and PSF files can contain distribution definitions. Neither file contains the path attribute. Its value is generated dynamically by swlist.

The bundles, media, and products attributes are not stored as attributes, but rather as bundle, media, and product definitions. These attributes are not included in swlist -v output. Rather, they are generated dynamically only by swlist -a attribute.

A PSF does not require a distribution definition. The PSF does not contain the uuid attribute. It is generated dynamically, if needed, by swcopy and swpackage.

An INDEX file contains the layout_version attribute as the first attribute defined in the file. Distributions which span multiple media contains the uuid attribute.

Media Definition

 

media
    sequence_number  sequence_number

INDEX files for distributions can contain media definitions.

An INDEX file for a distribution contains the sequence_number attribute if the distribution spans multiple media.

Installed Software Definition

 

installed_software
    layout_version   layout_version
    path             path
    dfiles           dfiles
    pfiles           pfiles
    catalog          catalog

The storage of catalogs for installed software is undefined. With the use of the swlist utility, the contents of such catalogs may be manifested in exported catalog form. The rules contained within this section applies when the contents of an installed software catalog is manifested in exported catalog form.

INDEX files can contain installed_software definitions. This describes the attributes for installed_software objects when listed in exported catalog structure using swlist.

The products and bundles attributes are not stored as attributes, but rather as product and bundle definitions. These attributes are not included in swlist -v output. Rather, they are generated dynamically only by swlist -a attribute .

An INDEX file does not contain the path or catalog attributes; they are generated dynamically by swlist.

An INDEX file contains the layout_version attribute as the first attribute defined in the file.

Vendor Definition

 

vendor
    tag                tag
    title              title
    description        description

INDEX and PSF files can contain vendor definitions. The tag attribute is required for all vendor objects.

Category Definition

 

category
    tag                tag
    title              title
    description        description
    revision           revision

INDEX and PSF files can contain category definitions. The tag attribute is required for all category objects.

Bundle Definition

 

bundle
    tag                tag
    architecture       architecture
    category_tag       category_tag
    location           location
    qualifier          qualifier
    revision           revision
    vendor_tag         vendor_tag
    contents           contents
    copyright          copyright
    create_time        create_time
    description        description
    directory          directory
    instance_id        instance_id
    is_locatable       is_locatable
    is_locatable       is_locatable
    is_patch           is_patch
    machine_type       machine_type
    mod_time           mod_time
    number             number
    os_name            os_name
    os_release         os_release
    os_version         os_version
    size               size
    title              title

INDEX and PSF files can contain bundle definitions. The tag and contents attributes are required for all bundles.

Neither file contains the size attribute. The value of the size attribute is generated dynamically based on the sizes of the filesets currently contained within the bundle.

An INDEX file also contains an instance_id attribute. The value of the instance_id attribute is generated dynamically by swpackage or swcopy. An INDEX file for installed software contains a create_time attribute and a mod_time attribute for each bundle.

Only bundle definitions for installed software may contain either the location or qualifier attributes; bundle definitions for distributions do not contain either the location or qualifier attributes.

A PSF should not contain either the location or qualifier attributes; they are ignored when parsing the file.

Product Definition

 

product
    tag                  tag
    architecture         architecture
    category_tag         category_tag
    qualifier            qualifier
    revision             revision
    vendor_tag           vendor_tag
    all_filesets         all_filesets
    control_directory    control_directory
    copyright            copyright
    create_time          create_time
    directory            directory
    description          description
    instance_id          instance_id
    is_locatable         is_locatable
    is_patch             is_patch
    postkernel           postkernel
    location             location
    machine_type         machine_type
    mod_time             mod_time
    number               number
    os_name              os_name
    os_release           os_release
    os_version           os_version
    size                 size
    title                title

INDEX and PSF files can contain product definitions. The tag and control_directory attributes are required for all products.

Neither file contains the size attribute. The value of the size attribute is generated dynamically based on the sizes of the filesets currently contained within the product.

An INDEX file for installed software contains a create_time attribute and a mod_time attribute for each product.

The control_files, filesets, and subproducts attributes are not stored as attributes, but rather as control_file, fileset, and subproduct definitions. These attributes are not included in swlist -v output. Rather, they are generated only by swlist -a attribute .

An INDEX file contains an instance_id attribute. The value of the instance_id attribute is generated by swpackage or swcopy. An INDEX file also contains a all_filesets attribute in addition to the fileset definitions. This attribute is generated by swpackage and represents all filesets defined for the product, as opposed to those that are currently contained within the product. The value of the filesets and all_filesets attributes may differ, since some originally defined filesets might not be copied or installed. Only product definitions for installed software may contain either the location or qualifier attributes; product definitions for distributions do not contain either the location or qualifier attributes.

A PSF should not contain either the location or qualifier attributes; they are ignored when parsing the file.

Subproduct Definition

 

subproduct
    tag                tag
    contents           subproducts
    category_tag       category_tag
    create_time        create_time
    description        description
    is_patch           is_patch
    mod_time           mod_time
    size               size
    title              title

INDEX and PSF files can contain subproduct definitions. The tag and contents attributes are required for all subproducts.

Neither file contains the size attribute. The value of the size attribute is generated dynamically based on the sizes of the filesets currently contained within the subproduct.

An INDEX file for installed software contains a create_time attribute and a mod_time attribute for each subproduct.

Fileset Definition

 

fileset
    tag                    tag
    ancestor               ancestor
    applied_patches        applied_patches
    category_tag           category_tag
    control_directory      control_directory
    corequisites           corequisites
    create_time            create_time
    description            description
    exrequisites           exrequisites
    is_reboot              is_reboot
    is_kernel              is_kernel
    is_locatable           is_locatable
    is_patch               is_patch
    is_sparse              is_sparse
    location               location
    media_sequence_number  media_sequence_number
    mod_time               mod_time
    patch_state            patch_state
    prerequisites          prerequisites
    revision               revision
    saved_files_directory  saved_files_directory
    size                   size
    state                  state
    superseded_by          superseded_by
    supersedes             supersedes
    title                  title

INDEX and PSF files can contain fileset definitions. The tag and control_directory attributes are required for all filesets.

The control_files and files attributes are not stored as attributes, but rather as control_file and file definitions. These attributes are not included in swlist -v output. Rather, they are generated only by swlist -a attribute .

An INDEX file contains a size attribute for each defined fileset. Fileset definitions for distributions that span multiple media contain the media_sequence_number attribute. An INDEX file for installed_software contains a create_time and a mod_time attribute for each fileset.

A PSF should not contain the applied_patches, location, media_sequence_number, patch_state, saved_files_directory, size, state, or superseded_by attributes; they are ignored when parsing the file. The value of the size attribute is generated dynamically by swpackage based on the sizes of the files and control_files.

When defining a patch, the attributes that must be defined are the files to be patched, and the fileset attribute is_patch. This automatically sets the category_tag patch; the patch category can not be specified in a PSF file. The product containing a patch or sparse fileset must have a different tag or revision attribute from the product containing the ancestor fileset being updated.

Control_File Definition

 

control_file
    tag               tag
    cksum             cksum
    compressed_cksum  compressed_cksum
    compressed_size   compressed_size
    compression_state compression_state
    compression_type  compression_type
    interpreter       interpreter
    path              path
    revision          revision
    size              size
    source            source
    result            result

INFO and PSF files can contain control_file definitions.

A PSF should not contain the cksum, compressed_cksum, compressed_size, compression_state, compression_type, size, or result attributes; they are ignored when parsing the file. The values of the size and cksum attributes are generated dynamically by swpackage based on the source file. A PSF contains a source attribute. A PSF can contain a path attribute. If it does not, swpackage uses the basename obtained from the value of the source attribute as the value of the path attribute. A PSF can contain a tag attribute. If it does not, swpackage uses the basename obtained from the value of the path attribute as the value of the tag attribute. The swpackage utility resolves the value of the tag attribute after it resolves the value of the path attribute.

An INDEX file contains the tag, path, cksum, and size attributes. Control_file definitions for installed software also contain the result attribute. INDEX files should not contain the source attribute; it is ignored when parsing the file.

The swpackage command automatically includes the INFO file itself as a control file and adds the tag, path, and size attributes for it. The value of the cksum attribute for the INFO control_file itself is not defined. An implementation can choose to store certain software object attributes, such as copyright, as control_files.

File Definition

 

file
    path              path
    archive_path      archive_path
    cksum             cksum
    compressed_cksum  compressed_cksum
    compressed_size   compressed_size
    compression_state compression_state
    compression_type  compression_type
    gid               gid
    group             group
    is_volatile       is_volatile
    link_source       link_source
    major             major
    minor             minor
    mode              mode
    mtime             mtime
    owner             owner
    revision          revision
    size              size
    source            source
    type              type
    uid               uid

INFO and PSF can contain file definitions.

A PSF contains a source attribute. A PSF should not contain the cksum compressed_cksum, compressed_size, compression_state, compression_type, or size attributes; they are ignored when parsing the file. Device files (including the major and minor attributes) should not be defined in a PSF (but can be added via swmodify after being created by a configure script); they are ignored when parsing the file. The values of the size and cksum attributes are generated dynamically by swpackage based on the source file. A PSF can contain a path attribute, otherwise the source is used to defined the path by swpackage. A PSF can contain gid, group, link_source, mode, mtime, owner, type, and uid attributes, otherwise they are retrieved from the source file by swpackage. A PSF can contain is_volatile and revision attributes. Automatic determination of the file revision is implementation defined.

An INFO file should not contain the source attribute; it is ignored when parsing the file. File Attributes for INFO File shows the required, optional and non-applicable attributes for each of the file types in an INFO file. The file types are described in Attributes of the Control File Class . Within a fileset, no more than one copy of a file is stored with the same path.

Table: File Attributes for INFO File

 



Key:
R  Required


O  Optional


-   Ignored

Within a PSF file, if the same file is defined more than once, the attributes from the last definition are used and they redefine the attributes previously defined. This action does not cause additional copies of the file to be stored in the distribution. All attributes not specifically listed remain unchanged.

Extended Control_File Definitions

 

checkinstall   source [path]
preinstall     source [path]
postinstall    source [path]
verify         source [path]
fix            source [path]
checkremove    source [path]
preremove      source [path]
postremove     source [path]
configure      source [path]
unconfigure    source [path]
request        source [path]
unpreinstall   source [path]
unpostinstall  source [path]
space          source [path]
control_file   source [path]

A PSF can contain extended control_file definitions. Each control_file definition defines the source attribute (the source file) to be used for the script. The keyword (meaning checkinstall, preinstall, etc.) defines the tag of the script, which tells the utilities when to execute the script.

If the optional path is supplied, it is the file name in the distribution (relative to the control directory for the software containing this script) used to store the file; otherwise, the control_file.tag attribute is used as the file name. This also allows a vendor to define one script to be executed for multiple tags. The script can determine the tag being executed by the SW_CONTROL_TAG environment variable.

If the control_file keyword is used, then the basename of the source attribute is the tag of the control_file.

Extended File Definitions

directory mapping

A PSF can point the swpackage utility at a source directory containing the files for the fileset. In addition, a PSF can map this source directory to the appropriate (destination) directory containing this subset of the filesets files.

recursive (implicit) file definition

If a directory mapping is active, a PSF can direct the swpackage utility to include all files (recursively) from within the directory in the fileset.

explicit file definition

For all or some of the files in the fileset, a PSF can name each source file and destination path with a one line per file syntax.

default permission definition

For all or some of the files in the fileset, a PSF can define a default set of permissions.

excluding files

Files that otherwise would be included can be explicitly excluded.

including files

File definitions may be included from a separate file.

These mechanisms can all be used in combination with the others.

Directory Mapping

 

directory    source  [path]

This syntax defines a source directory under which subsequently listed files are located. In addition, the user can map the source directory to a destination directory under which the packaged files will be located.

The destination directory is an absolute pathname and is used as a prefix to the path attribute for each of the files.

The source directory can be either an absolute pathname, or a relative pathname. If relative, the swpackage utility interprets it relative to the current working directory in which the utility was invoked.

If the source directory does not exist, the swpackage utility generates an error.

Recursive File Definition

 

file  *

This syntax directs the swpackage utility to include every file (and directory) within the current source directory in the fileset. The swpackage utility attempts to include the entire, recursive contents of the source directory in the fileset.

The directory keyword is specified before the file * specification is used. After finishing the recursive processing of the source directory, the swpackage utility processes further specifications with respect to the original directory.

All other attributes for the destination file object are taken from the source file, unless a file_permission keyword is active. This keyword is described below.

The user can specify multiple directory and file * pairs to gather all files from different source directories into a single fileset.

Explicit File Definition

Instead of, or in addition to, the recursive file specification, the user can explicitly specify the files to be packaged into a fileset.

This syntax may be used to redefine an attribute of a previously defined file. All attributes not specifically listed remain the same.

The directory keyword can be used to define a source (and destination) for explicitly specified files. If no directory keyword is active, then the full source path and the absolute destination path (the path attribute) is specified for each file.

The meaning of each of these fields is as follows:

file

This keyword specifies an existing file or directory, perhaps within the currently active source directory, to include in the fileset. It can also specify a directory, hard link, or symbolic link that does not exist as a source file, but is created when the fileset is installed.

source

When specifying an existing source file, this value defines the path to it.

If this is a relative path, the swpackage utility searches for it relative to the source directory set by the directory keyword. If no source directory is active, the swpackage utility searches for it relative to the current working directory in which the utility was invoked.

All attributes for the destination file object are taken from the source file, unless a file_permission keyword is active, or the -m, -o, or -g options are also included in the file specification.

When specifying a new directory to be created upon installation, and there is no destination path specified, the source defines the path of the installed directory. When specifying a new hard link or symbolic link to be created upon installation, the source defines the pathname of the installed file to use as the source for the new file.

path

When specifying a new or existing source file, this value defines the destination path at which the file will be created or installed. If path is a relative path, the active destination directory set by the directory keyword is prefixed to it. If the path is relative, and no destination directory is active, the swpackage utility generates an error. If the path is not specified, then the source is used as the path, with the appropriate mapping done with the active destination directory (if any).

-t type

When creating a new directory, hard link or symbolic link (a file in the fileset that does not exist in the source), this option is specified to define the file type. The following file types can be created:

d

Create a directory. If only the source is specified, it is used as the path. Otherwise, the source is used to retrieve the attributes for the directory created at path. If the path is not specified, or any attributes, then default values of the attributes is implementation defined.

h

Create a hard link. Both the source and path are specified. The source is the pathname of the installed file object to be used as the source for the new hard link (the link_source attribute).

s

Create a symbolic link. Both the source and path are specified. The source is the pathname of the installed file object to be used as the source for the new symbolic link (the link_source attribute).

x

Delete a file. The remove type, x for the file type attribute deletes any existing file instead of installing a new file or link.

Files with the types c (character special), b (block special) and p (named pipe | FIFO) are not supported by swpackage and swinstall and can be created via a configure control script. In general, device files and pipes are created during system configuration on the system actually running the software. Also, there can be files of other types that the swpackage utility does not recognize and which therefore cause an error.

-m mode

This option defines the (octal) mode for a file or directory.

-o [owner][,uid]

This option defines the owner name and/or or uid of the destination file. If only the owner is specified, then the owner and uid attributes are set for the destination file object, based on the database of the packaging host. If only the uid is specified, it is set as the uid attribute for the destination object and no owner name is assigned. If both are specified, each sets the corresponding attribute for the file object. If neither are specified, then the owner and uid of the file are used as found in the file system of the packaging host. See "File Loading" in the definition for swinstall tagmref_swinstall .

During an installation, the owner attribute is used to set the owner name and uid, unless the owner name is not defined in the target system user database. In this case, the value of the uid attribute is used to set the uid.

-g [group][,gid]

This option defines the group name and/or gid of the destination file. If only the group is specified, then the group and gid attributes are set for the destination file object based on the database of the packaging host. If only the group is specified, and it contains digits only, it is interpreted as the gid, and is set as the gid attribute for the destination object; no group name is assigned to the object. If both are specified, each sets the corresponding attribute for the file object. If neither are specified, then the group and gid of the file are used as found in the file system of the packaging host. See "File Loading" in the definition for swinstall tagmref_swinstall .

During an installation, the group attribute is used to set the group name and gid, unless the group name is not defined in the target system group database. In this case, the gid attribute is used to set the gid.

-n

This option indicates that the file is not compressible.

-v

The use of -v on a source line is used to specify that the file is volatile (contents, attributes or existence can change after installation).

Default Permission Definition

file_permissions [-m mode | -u umask][-o [owner[,]][uid]]


                 [-g [group[,]][gid]]

A destination file object inherits the mode, owner, and group of the source file. The file_permissions keyword can be specified to set a default permission mask, owner, and group for all the files being packaged into the fileset:

file_permissions

This keyword only applies to the fileset it is defined in. Multiple file_permissions can be specified, and subsequent definitions simply replace previous definitions.

-m mode

This option defines a default (octal) mode for all file objects.

-u umask

Instead of specifying an octal mode as the default, the user can specify an octal umask() value that gets "subtracted" from the mode of an existing source file, or applied for each non-existent file, to generate the mode of the destination file.

By specifying a umask() value the user can set a default mode for executable files, non-executable files, and directories. A specific mode can be set for any file, as described above.

-o\ [owner[,]][uid]

This option defines the owner name and/or uid of the destination file. See the discussion of the -o option in Explicit File Definition .

-g\ [group[,]][gid]

This option defines the group name and/or gid of the destination file. See the discussion of the -g option in Explicit File Definition .

Excluding Files

 

exclude source

A file listed after the exclude keyword that was previously included, for example from a recursive file definition, is excluded from the list of files.

If the source specifies a directory, then all files below that directory are excluded.

Including Files

 

file < include_file

The file keyword can be used to include definitions for files from a separate include_file by specifying a < (less than) character followed by the include_file.

Space Control_file

 

path    [+|-]size

For each path listed in the space file, the swinstall utility adds the size, in bytes, to the disk space requirements. The size can be positive (reflecting the maximum transient or permanent disk space required for the install), or negative (reflecting space freed by one of the scripts executed by the swinstall command). An implementation must consider positive records and may consider negative records.

Serial Format and Multiple Media

A serial distribution can be stored on any serial medium. A serial distribution can also be stored in any file, within the file system, which supports the storing of POSIX.1 extended cpio or extended tar archives. How a system reads or writes to the different media devices is outside the scope of this Software Administration specification.

Implementations support serial distributions if the underlying operating system supports the pax utility, as defined in POSIX.2, or otherwise supports reading and writing of the extended tar and extended cpio archives defined in POSIX.1. If serial distributions are supported, the serial distribution formats supported include extended tar and extended cpio.

The distribution is implemented as a set of one or more POSIX.1 extended cpio or extended tar archives. The archives reside on a set of one or more serial media, or in a file. Each media in a serial distribution contains one and only one archive.

A distribution may span multiple media in a hierarchical structure. In this case, the set of files on any particular media, including the attributes defined in any software definition files, should be similar to that for a serial archive. In other words, the decision for which files are put on which media should be the same whether the distribution is serial or hierarchical. Space considerations on media may cause some differences.

The following are the rules regarding ordering of files within serial distributions. These rules, including generation of the fileset.media_sequence_number, are implemented by the swpackage utility.

1. The catalog files (which contain all the information describing the software contained in the distribution), as well as the control scripts, in this relative order:

   1. The global INDEX file, as described in Exported Catalog Structure .

   2. The distribution files, as described in Exported Catalog Structure .

   3. The product catalog files, product by product, as described in Exported Catalog Structure .

      1. The product control files, as described in Exported Catalog Structure .

      2. The fileset control files, fileset by fileset, as described in Exported Catalog Structure .

2. The actual software files, fileset by fileset, as described in File Storage Structure .

   1. Prerequisites of filesets before the filesets that depend on them

   2. Kernel filesets before non kernel filesets (except where kernel filesets have prerequisites on non-kernel)

3. Each medium has (as its first file, if a serial medium)

   1. A global INDEX file, catalog/INDEX that contains at least the distribution.uuid and media.sequence_number attributes (used to identify a particular media within a particular distribution)

4. Each archive starts at the beginning of the medium. Multiple archives on one medium are not allowed.

Additionally, in order to increase the usability of multiple media serial distributions, the following guidelines should be used and in decreasing importance:

• Each medium should contain complete files wherever possible. If a file is larger than the the capacity defined by the media_capacity option, then the behavior is implementation defined.

• Each medium should contain complete filesets whenever possible or practical. The fileset.media_sequence_number attribute is the number of the medium where the fileset begins. If a fileset is larger then the medium size, then the fileset.media_sequence_number attribute contains the list of media.sequence_numbers describing the media that contain this fileset.

• Each medium should contain complete products whenever possible or practical.

• Each medium should contain needed dependencies whenever possible or practical.

Thus a conforming implementation is able to:

• Read the INDEX off of the first medium for the Selection Phase

• Scan the first medium (and those following as needed) for the necessary catalog files for the Analysis Phase

• Request the next needed medium for the next needed fileset based on media_sequence_number during the Execution Phase

• Request the next medium when the fileset spans media

Note that in all respects, a serial distribution conforms to the specifications of the extended cpio or extended tar archives. See POSIX.1. This includes, but is not limited to, the following:

• Recording format

• Character sets

Footnotes

1.

Refer to Sample File Coding for examples of the use of this syntax.