intro_libsam(3X)

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

AVAILABILITY
     SUNWqfs

     SUNWsamfs

DESCRIPTION
     The Sun QFS and SAM-QFS API allows a Sun QFS or SAM-QFS file
     to be requested from within an application program.  The
     aplication program can reside either on the machine upon
     which the Sun QFS or 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:

     o API overview

     o API library routines

     o Using libsam

     o 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 QFS or 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 QFS
     or 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 QFS and SAM-QFS
     file systems are as follows:

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

     o 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 QFS or 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 QFS and 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 QFS and SAM-QFS
                    environments.
                    Libraries:  libsam.

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

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

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

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

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

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

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

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

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

     sam_closerpc   Closes down the RPC connection.
                    Availability:  SAM-QFS environments.
                    Libraries:  libsamrpc.

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

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

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

     sam_initrpc    Initializes the RPC connection.
                    Availability:  SAM-QFS environments.
                    Libraries:  libsamrpc.

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

     sam_readrminfo Gets information for a removable media file.
                    Availability:  SAM-QFS environments.

                    Libraries:  libsam.

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

     sam_request    Creates a removable media file.
                    Availability:  SAM-QFS environments.
                    Libraries:  libsam.

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

     sam_restore_file
                    Creates an offline file.
                    Availability:  SAM-QFS environments.
                    Libraries:  libsam.

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

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

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

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

     sam_stage      Stages and sets stage attributes on a file.
                    Availability:  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 QFS and 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:  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.
     Oracle Corporation 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:

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

     o 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  # SAM-QFS 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:

     o The name of the server machine.

     o 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 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).