intro_libsam(3)

NAME
intro_libsam, intro_libsamrpc - Introduces the Sun StorageTek QFS and Sun StorageTek SAM-FS Application Programmer Interface (API) routines

AVAILABILITY
SUNWqfs

SUNWsamfs

DESCRIPTION
The Sun StorageTek QFS and Sun StorageTek SAM-FS API allows a Sun StorageTek QFS, Sun StorageTek SAM-FS, or Sun SAM-QFS file to be requested from within an application program. The aplication program can reside either on the machine upon which the Sun StorageTek QFS, Sun StorageTek SAM-FS, or Sun SAM-QFS file system is running or on another machine on the network. This man page provides an introduction to the API routines.

The following topics are presented:

•   API overview

•   API library routines

•   Using libsam

•   Using libsamrpc

API OVERVIEW
When a request is made, the process or program making the request is the client process or program, running on the client machine. The requests are received and processed by the server, running on the server, or host, machine. For the API routines, the server machine is always the machine upon which the Sun StorageTek QFS, Sun StorageTek SAM-FS, or Sun SAM-QFS file system is running.

In the simplest case, the client and server machines are the same, and no network communication is necessary. In other cases, however, the application programmer needs to allow for the client program to run on a machine where the Sun StorageTek QFS, Sun StorageTek SAM-FS, or Sun SAM-QFS file system is not running. In this case, networked library calls from libsamrpc must be used.

The two API libraries available with the Sun StorageTek QFS, Sun StorageTek SAM-FS, and Sun SAM-QFS file systems are as follows:

•   libsam. The library calls in libsam do not perform network communication. They only make local requests. In this case, each library call makes a system call, and the server is the local operating system.

•   libsamrpc. The library calls in libsamrpc use Remote Procedure Calls (RPCs) to communicate with a special server process, sam-rpcd. Because of the RPC mechanism, the client and server can exist on the same machine or on different machines in the network. The server process always runs on the machine upon which the Sun StorageTek QFS, Sun StorageTek SAM-FS, or Sun SAM-QFS file system is running.

Both libsam and libsamrpc are released in shared object (.so) and archive (.a) format for Solaris platforms. libsam.so and libsam.a are installed in /opt/SUNWsamfs/lib. libsamrpc.so and libsamrpc.a are installed in /opt/SUNWsamfs/client/lib, with symbolic links to them in /opt/SUNWsamfs/lib.

API LIBRARY ROUTINES
The library calls for the Sun StorageTek QFS, Sun StorageTek SAM-FS, and Sun SAM-QFS software are supported in libsam, and a subset is supported in libsamrpc.

Table 1 lists the API library routines and indicates the environments in which they are supported. In addition, table 1 indicates the libraries in which they are included:

Table 1. Library routine availability

Routine
    Description

sam_advise
    Sets file attributes.
    Availability: Sun StorageTek QFS, Sun StorageTek SAM-FS, and Sun SAM-QFS environments.
    Libraries: libsam.

sam_archive
    Sets archive attributes on a file.
    Availability: Sun StorageTek SAM-FS and Sun SAM-QFS environments.
    Libraries: libsam and libsamrpc.

sam_rearchive
    Sets rearchive attributes on a file.
    Availability: Sun StorageTek SAM-FS and Sun SAM-QFS environments.
    Libraries: libsam.

sam_exarchive
    Exchanges archive copies of a file or directory.
    Availability: Sun StorageTek SAM-FS and Sun SAM-QFS environments.
    Libraries: libsam.

sam_unarchive
    Removes archive copies for a file or directory.
    Availability: Sun StorageTek SAM-FS and Sun SAM-QFS environments.
    Libraries: libsam.

sam_unrearch
    Removes rearchive attributes on a file or directory.
    Availability: Sun StorageTek SAM-FS and Sun SAM-QFS environments.
    Libraries: libsam.

sam_damage
    Sets damaged attribute on a file or directory.
    Availability: Sun StorageTek SAM-FS and Sun SAM-QFS environments.
    Libraries: libsam.

sam_undamage
    Clears damaged and stale status of a file or directory.
    Availability: Sun StorageTek SAM-FS and Sun SAM-QFS environments.
    Libraries: libsam.

sam_cancelstage
    Cancels a pending or in-progress stage on a file.
    Availability: Sun StorageTek SAM-FS and Sun SAM-QFS environments.
    Libraries: libsam.

sam_closecat
    Ends access to the catalog for an automated library.
    Availability: Sun StorageTek SAM-FS and Sun SAM-QFS environments.
    Libraries: libsam.

sam_closerpc
    Closes down the RPC connection.
    Availability: Sun StorageTek SAM-FS and Sun SAM-QFS environments.
    Libraries: libsamrpc.

sam_devstat, sam_ndevstat
    Gets device status. sam_ndevstat accepts a longer device name.
    Availability: Sun StorageTek SAM-FS and Sun SAM-QFS environments.
    Libraries: libsam.

sam_devstr
    Translates numeric device status into a character string.
    Availability: Sun StorageTek SAM-FS and Sun SAM-QFS environments.
    Libraries: libsam.

sam_getcatalog
    Obtains a range of entries from the catalog for an automated library.
    Availability: Sun StorageTek SAM-FS and Sun SAM-QFS environments.
    Libraries: libsam.

sam_initrpc
    Initializes the RPC connection.
    Availability: Sun StorageTek SAM-FS and Sun SAM-QFS environments.
    Libraries: libsamrpc.

sam_opencat
    Accesses the VSN catalog for an automated library.
    Availability: Sun StorageTek SAM-FS and Sun SAM-QFS environments.
    Libraries: libsam.

sam_readrminfo
    Gets information for a removable media file.
    Availability: Sun StorageTek SAM-FS and Sun SAM-QFS environments.
    Libraries: libsam.

sam_release
    Releases and sets release attributes on a file.
    Availability: Sun StorageTek SAM-FS and Sun SAM-QFS environments.
    Libraries: libsam and libsamrpc.

sam_request
    Creates a removable media file.
    Availability: Sun StorageTek SAM-FS and Sun SAM-QFS environments.
    Libraries: libsam.

sam_restore_copy
    Creates an archive copy for a file.
    Availability: Sun StorageTek SAM-FS and Sun SAM-QFS environments.
    Libraries: libsam.

sam_restore_file
    Creates an offline file.
    Availability: Sun StorageTek SAM-FS and Sun SAM-QFS environments.
    Libraries: libsam.

sam_segment
    Sets segment attributes on a file or directory.
    Availability: Sun StorageTek SAM-FS and Sun SAM-QFS environments.
    Libraries: libsam and libsamrpc.

sam_segment_stat
    Obtains file information and follows symbolic links to a segmented file.
    Availability: Sun StorageTek SAM-FS and Sun SAM-QFS environments.
    Libraries: libsam.

sam_setfa
    Sets file attributes.
    Availability: Sun StorageTek QFS, Sun StorageTek SAM-FS, and Sun SAM-QFS environments.
    Libraries: libsam and libsamrpc.

sam_ssum
    Sets checksum attributes on a file.
    Availability: Sun StorageTek SAM-FS and Sun SAM-QFS environments.
    Libraries: libsam.

sam_stage
    Stages and sets stage attributes on a file.
    Availability: Sun StorageTek SAM-FS and Sun SAM-QFS environments.
    Libraries: libsam and libsamrpc.

sam_stat, sam_lstat
    sam_stat obtains file information and follows symbolic links to the file. sam_lstat obtains file information, and if that file is a link, it returns information about the link.
    Availability: Sun StorageTek QFS, Sun StorageTek SAM-FS, and Sun SAM-QFS environments.
    Libraries: libsam and libsamrpc.

sam_vsn_stat, sam_segment_vsn_stat
    Obtain VSN status for a file or a file's data segment that overflows VSNs.
    Availability: Sun StorageTek SAM-FS and Sun SAM-QFS environments.
    Libraries: libsam.

All APIs in libsam, except for sam_closecat, sam_getcatalog, and sam_opencat, are available for use with 64-bit programs. Sun Microsystems, Inc. does not support a 64-bit version of libsamrpc.

For more details about each library routine, see the individual corresponding man page for that routine. Library routines contained in libsam are found in section 3 of the online man pages. Library routines contained in libsamrpc are found in section 3X of the online man pages.

USING libsam
No special initialization or configuration is required prior to using the API library routines in libsam. The application program must be linked with libsam, however. For information on the routines, see the individual libsam man pages, all of which are listed in the SEE ALSO section of this man page.

USING libsamrpc
The source code for libsamrpc is included in the release for customers who wish to write and run application programs on platforms that do not run the Solaris operating system. In these cases, the library must be ported to the client machine. The source code is located in /opt/SUNWsamfs/client/src. Example application programs are located in /opt/SUNWsamfs/client/examples.

  Specifying the Server Machine
A call to sam_initrpc is required before any other RPC client API calls can be executed successfully. Only one sam_initrpc call is required, followed by any number of other client API calls (other than sam_closerpc). The sam_initrpc call accepts one argument: a pointer to a character string that specifies the name of the server machine. If this pointer is NULL, sam_initrpc checks for an environment variable named SAMHOST. If this environment variable is set, that name is used for the server machine. If there is no SAMHOST environment variable, the default server name samhost is used.

In summary, the name of the server machine can be specified in any of three ways, which are checked by sam_initrpc in the following order:

1.  As an argument to the sam_initrpc call.

2.  As the environment variable SAMHOST.

3.  By accepting the default server name, samhost.

  RPC Server Process
The RPC API server process receives and processes requests from the client. This server process, /opt/SUNWsamfs/sbin/sam-rpcd, must be run on the same machine as the file system. The sam-rpcd daemon must be running for client requests to execute successfully.

The sam-rpcd daemon is started automatically by sam-amld if the appropriate entry is made in the defaults.conf file. For information on editing the defaults.conf file, see Configuring the API later in this man page.

The sam-rpcd daemon can also be started manually. It should be run as superuser. The sam-rpcd command accepts no arguments.

The sam-rpcd daemon services the requests it receives by making the appropriate system call on the server machine and then returning the output or result to the client. For more information on this daemon, see the sam-rpcd(1M) man page.

  Configuring the API
The following steps describe setting up the API server and clients. These steps assume that your software is properly configured and running.

Step 1: Configure the API Server

For the server portion of the API to run successfully, the following conditions must be present:

•   The RPC program name and number pair must be known on the server machine

•   The RPC program name and number pair must be the same as the pair used on the API client machines.

Make an entry for the RPC program name and number. The RPC program number is a number chosen by you. The RPC program name is samfs. The name and number pair must be the same on the server and all clients. The /etc/nsswitch.conf file determines where you should specify the RPC program name and number pair. For more information on this, see the nsswitch.conf(4) man page.

In /etc/rpc (or the NIS database), add the following line:

samfs    150005

In /etc/services (or the NIS database), add the following line:

samfs    5012/tcp    # Sun StorageTek SAM-FS API

The API server is started automatically by the sam-amld daemon if the following entry is made in the defaults.conf file (note that changes to the defaults.conf file do not take effect until the next time the sam-amld daemon is initialized):

samrpc = on

The sam-rpcd daemon is not automatically started if no entry for it appears in the defaults.conf file or if the following entry appears in the file:

samrpc = off

For more information about the defaults.conf file, see the defaults.conf(4) man page.

Step 2: Configure the API Client Machines

The following two configuration components must be present on the client machine for the RPC communication to be successful:

•   The name of the server machine.

•   The RPC program name and number pair.

Make an entry for the RPC program name and number on all client machines, as you did on the API server machine previously. Again, the RPC program name must be samfs. The RPC program number is a number chosen by you, but it must be the same on the server and client machines.

In /etc/rpc (or the NIS database), add the following line:

samfs    150005

The host name of the server machine must be known on the client machine. For default cases, the host name samhost must be listed as an alias for the Sun StorageTek SAM-FS and Sun SAM-QFS file system server machine. For more information, see the sam_initrpc(3X) man page.

  Authentication and libsamrpc
Authentication information is generated at the time of the sam-initrpc call. This information consists of the user identification (uid) and group identification (gid) of the calling process. It is associated with the connection made to the RPC server process.

Subsequent libsamrpc calls have this information associated. When the request is received by the RPC server process on the server machine, the uid and gid information is used. File access and operations are granted or denied based on this information.

It is important that the server machine have a common uid and gid space with the client machines.

SEE ALSO
sam_advise(3), sam_archive(3), sam_rearch(3), sam_exarchive(3), sam_unarchive(3), sam_unrearch(3), sam_damage(3), sam_undamage(3), sam_cancelstage(3), sam_closecat(3), sam_devstat(3), sam_devstr(3), sam_getcatalog(3), sam_lstat(3), sam_ndevstat(3), sam_opencat(3), sam_readrminfo(3), sam_release(3), sam_request(3), sam_restore_copy(3), sam_restore_file(3), sam_segment(3), sam_setfa(3), sam_ssum(3), sam_stage(3), sam_stat(3).

sam_archive(3X), sam_closerpc(3X), sam_initrpc(3X), sam_lstat(3X), sam_release(3X), sam_stage(3X), sam_stat(3X).