sam_ssum(3)

NAME
sam_ssum - Sets checksum 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 checksum attributes on a file using a Sun StorageTek SAM-FS or Sun SAM-QFS 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 128-bit value is generated when the file is archived. When the file is subsequently staged, the checksum is again generated and is compared against the value generated at archive time if the use (-u) attribute is set. By default, no checksum 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 checksum generate or use attributes set. Also, it is not valid to specify that a file never be archived as well as specify that a checksum 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 checksum generate or use attribute on the file will result in an error and the attributes will be unchanged. Similarly, when either the checksum 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 checksum 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 checksum attributes to the default.

g   Generate a checksum value for the file when archiving.

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

n   n is an integer specifying the algorithm to use to generate the 128-bit checksum value. The simple checksum algorithm provided by Sun Microsystems, Inc. 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   Use a simple checksum algorithm that also factors in file length.

    128 or higher
        Site-specified algorithms.

    For example, a valid options string is "gu1", setting the generate and use attributes, and specifying that the Sun-provided simple checksum algorithm be used to generate the value.

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.

SEE ALSO
archive(1), release(1), sls(1) ssum(1), stage(1).

sam_archive(3), sam_release(3), sam_stage(3).