NAME

sam_ssum - Sets message-digest attributes on a file

SYNOPSIS

cc [ flag … ] file … -L∕opt∕SUNWsamfs∕lib -lsam [ library … ]

#include "∕opt∕SUNWsamfs∕include∕lib.h"

int sam_ssum(const char * path , const char * ops );

DESCRIPTION

sam_ssum() sets the message-digest attributes on a file using a Oracle HSM system call. path is the file on which to set the attributes. ops is the character string of options, for example: "gu". Individual options are described below.

If the generate (g) attribute is set (-g), a message-digest value is generated when the file is archived. When the file is subsequently staged, the message-digest is again generated and is compared against the value generated at archive time if the use (-u) attribute is set. By default, no message-digest value is generated or used when archiving or staging a file.

The generate attribute must be set on a file before any archive copy has been made. Likewise, the selected algorithm cannot be changed after an archive copy has been made.

Direct access and partial release are not allowed on a file that has either of the message-digest generate or use attributes set. Also, it is not valid to specify that a file never be archived as well as specify that a message-digest be generated and∕or used. Therefore, when a direct access, partial release, or archive never attribute is set on a file, attempting to set the message-digest generate or use attribute on the file will result in an error and the attributes will be unchanged. Similarly, when either the message-digest generate or use attribute is set on a file, attempting to set a direct access, partial release, or archive never attribute on the file will result in an error and the attributes will be unchanged.

A file that has the message-digest use attribute set cannot be memory mapped. The file also must be completely staged to the disk before access is allowed to the file's data; this means that accessing the first byte of offline data in an archived file that has this attribute set will be slower than accessing the same offline file when it does not have this attribute set.

OPTIONS

d

Return the file's message-digest attributes to the default. A file that has fixity specfified and has a validated message digest cannot return to default attributes.

g

Generate a message-digest value for the file when archiving.

u

Use the message-digest value for the file when staging. The generate attribute must have been previously set, or must be set simultaneously.

F

This option sets the fixity option which provides a means to assure file correctness and detect file modifications. When set, the message-digest for the file will not be changed by Oracle HSM. If the h option is specified with this options, the supplied message-digest is immediately checked against the file. This option can only be specified for a regular file but cannot be used on a segmented file. See fixity (7) for additional information.

G

This causes the function to immediately calculate the message-digest of the file. If the h option is specified with this option, the supplied message-digest is immediately checked against the file. If the values do not match the function returns an error. When the values match or no h option is supplied the message-digest is saved for the file and its generate and use attributes are set. This option can only be specified for a regular file but cannot be used on a segmented file.

an

Specify the message-digest algorithm. n is an integer specifying the algorithm to use to generate the 128-bit message-digest value. The simple 128-bit checksum algorithm provided by Oracle is the default if no algorithm is specified but the generate attribute is set. n may be one of the following:

0

Use no algorithm.

1

Reserved.

2

Use a simple 128-bit checksum algorithm that also factors in file length. This is the legacy Oracle HSM checksum algorithm.

3

Use the 128-bit MD5 message-digest algorithm.

4

Use the 160-bit SHA-1 message-digest algorithm.

5

Use the 256-bit SHA-256 message-digest algorithm.

6

Use the 384-bit SHA-384 message-digest algorithm.

7

Use the 512-bit SHA-512 message-digest algorithm.

For example, a valid options string is "gua4", setting the generate and use attributes, and specifying that the SHA-256 message-digest algorithm be used to generate the value.

h…

Specify the message-digest value for the file. The message-digest value must have been generated using the specified algorithm and encoded as a ASCII hexadecimal string, i.e., 4-bits per character. If a message-digest is specified and fails to match the file the operation fails. This option must be the last in the options string.

ERRORS

sam_ssum() fails if one or more of the following are true:

EINVAL: An invalid option was specified, or the file is neither a regular file nor a directory.
EPERM: Not the owner or super-user.
EFAULT: path or ops points to an illegal address.
EINTR: A signal was caught during the sam_ssum() function.
ELOOP: Too many symbolic links were encountered in translating path.
ENAMETOOLONG: The length of the path argument exceeds {PATH_MAX}, or the length of a path component exceeds {NAME_MAX} while {_POSIX_NO_TRUNC} is in effect.
ENOENT: The named file does not exist or is the null pathname.
ENOLINK: path points to a remote machine and the link to that machine is no longer active.
ENOTDIR: A component of the path prefix is not a directory.