Skip Navigation Links | |
Exit Print View | |
Sun QFS and Sun Storage Archive Manager 5.3 Reference Manual Sun QFS and Sun Storage Archive Manager 5.3 Information Library |
1. User Commands (Man Pages Section 1)
2. Maintenance Commands (Man Pages Section 1M)
3. Library Functions (Man Pages Section 3)
4. Library Functions (Man Pages Section 3X)
5. File Formats (Man Pages Section 4)
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).