Introduction to Library Functions 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: 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 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: 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 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: 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 # 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: 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 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). Sun Microsystems Last change: 15 May 2007 Introduction to Library Functions 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: 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 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: 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 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: 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 # 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: 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 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). Sun Microsystems Last change: 15 May 2007 Introduction to Library Functions qfs_listio(3) NAME qfs_lio_read, qfs_lio_write, qfs_lio_poll, qfs_lio_wait - Issues list I/O or waits for listio. SYNOPSIS cc [flag ...] file ... -L/opt/SUNWsamfs/lib -R/opt/SUNWsamfs/lib -lsam [library ...] #include "/opt/SUNWsamfs/include/listio.h" int qfs_lio_init(qfs_lio_handle_t *hdl); int qfs_lio_read(int fd, int mem_list_count, void **mem_addr, size_t *mem_count, int file_list_count, offset_t *file_off, offset_t *file_len, qfs_lio_handle_t *hdl); int qfs_lio_write(int fd, int mem_list_count, void **mem_addr, size_t *mem_count, int file_list_count, offset_t *file_off, offset_t *file_len, qfs_lio_handle_t *hdl); int qfs_lio_wait(qfs_lio_handle_t *hdl); AVAILABILITY SUNWqfs SUNWsamfs DESCRIPTION The qfs_lio_read() function issues a listio read for an open file descriptor. The qfs_lio_write() function issues a listio write for an open file descriptor. The qfs_lio_init() must be used to initialize a handle object before passing it to one of the other interfaces. The qfs_lio_wait() can be issued to wait until all I/O in the listio call has completed. ARGUMENTS These functions accept the following arguments: fd issues I/O for a file using a Sun StorEdge QFS or Sun SAM-FS ioctl call. mem_list_count is the number of elements in the mem_addr and mem_count arrays. mem_addr, mem_count are arrays describing a list of memory regions. file_list_count is the number of elements in the file_off and file_len arrays. file_off, file_len are arrays describing a list of file regions. hdl points to an opaque value that is used to indicate the status of an asynchronous list I/O request. If hdl is non-null, the function returns when all I/O has issued. If hdl is NULL, the function returns when all I/O has been completed. RETURN VALUES Upon successful completion a value of 0 is returned. Otherwise, a value of -1 is returned and errno is set to indicate the error. ERRORS The qfs_lio_read(), qfs_lio_write(), and qfs_lio_wait() fails if one or more of the following are true: EINVAL An invalid option was specified, or the file is not a regular file. EPERM Not the owner or super-user. EFAULT mem_addr, mem_count, file_off, or file_len points to an illegal address. EINTR A signal was caught during the qfs_lio() function. SEE ALSO setfa(1), sam_setfa(3), directio(3C), Sun Microsystems Last change: 10 Feb 2005 Introduction to Library Functions sam_advise(3) NAME sam_advise - Provides advice to the file system SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsam [ library ... ] #include "/opt/SUNWsamfs/include/lib.h" int sam_advise(const int fildes, const char *ops); DESCRIPTION sam_advise() provides advice about expected behavior of the application when accessing data in the file associated with the open file descriptor, fildes. sam_advise() provides advice for a file using a SAM-QFS ioctl call. The last caller of sam_advise() sets the advice for all applications using the file. The last close of the file sets the advice back to the default mode. ops is the character string of options, for example: "dw". Individual options are described below. OPTIONS b Advises the system to use buffered (paged) I/O. The default I/O mode is buffered (uses the page cache). At the last close, the type of I/O is set back to paged or direct based on the mount option forcedirectio or the directio attribute set by the setfa command. d Return the advice on the file to the default, i.e. the qwrite is reset to the mount setting. When this option is specified, the advice is reset to the default. If it is used, it should be the first character in the string. p Obsolete. Now does nothing, but remains for compati- bility. r Advises the system to use direct (raw) I/O (see directio(3C) for Solaris 2.6 and above). The default I/O mode is buffered (uses the page cache). At the last close, the type of I/O is set back to paged or direct based on the mount option forcedirectio or the directio attribute set by the setfa command. w Advises the system to enable simultaneous reads and writes to the same file from different threads. See the qwrite parameter on the mount command. The w option is only supported by the ma equipment type file system. (See man mcf(4)). RETURN VALUES Upon successful completion a value of 0 is returned. Other- wise, a value of -1 is returned and errno is set to indicate the error. ERRORS sam_advise() fails if one or more of the following are true: EINVAL An invalid option was specified, or the file is not a regular file. EPERM Not the owner or super-user. EFAULT path or ops points to an illegal address. EINTR A signal was caught during the sam_advise() function. ELOOP Too many symbolic links were encountered in translating path. EMULTIHOP Components of path require hopping to multiple remote machines and the file system does not allow it. ENAMETOOLONG The length of the path argument exceeds {PATH_MAX}, or the length of a path com- ponent 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 setfa(1), sam_setfa(3), directio(3C), mlock(3C), mount_samfs(1M), mcf(4) Sun Microsystems Last change: 16 Mar 2005 Introduction to Library Functions sam_archive(3) NAME sam_archive - Sets archive attributes on a file or directory SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsam [ library ... ] #include "/opt/SUNWsamfs/include/lib.h" int sam_archive(const char *path, const char *ops); DESCRIPTION sam_archive() sets archive attributes on a file or directory using a Sun StorEdge 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: "dn". Individual options are described below. OPTIONS C Specifies concurrent archiving for this file. This file can be archived even if opened for write. The archive time is regulated by the modification time. Note, nfs files are not opened and are by default concurrently archived. Concurrent archiving is useful for databases, however caution is advised since archiving can occur while the file is being modified and this can result in wasted media. The default is to disallow archiving while the file is opened for write. I Support inconsistent archive copies. This means that an archive copy can be created even if the file is modi- fied while it is being copied to the media. By default, the archive copy is disallowed if the file is incon- sistent, that is, if the file is modified while it was being copied to the media. Note, the file cannot be staged if the copy is marked inconsistent; however, after a samfsrestore, the inconsistent flag is removed from the archive copy and the file can be staged. Inconsistent archiving is useful for databases, however caution is advised because it a file can be staged from an inconsistent copy after the file is restored using samfsrestore. d Return the archive attributes on the file to the default, i.e. archive the file according to the archiver rules. When this option is specified, the attributes are reset to the default. If it is used, it should be the first character in the string. i Specifies that the file be immediately archived if it is not already archived. w Wait for the file to have at least 1 archive copy before completing. Not valid with d or n. Note that it may take a long time for the file to be archived. W Wait for the file to have all its required archive copies before completing. Not valid with d or n. Note that it may take a long time for the file to be archived. n Specifies that this file never be archived. Not valid with either of the checksum g (generate) or u (use) attributes. (See ssum(1) or sam_ssum(3)). RETURN VALUES Upon successful completion a value of 0 is returned. Other- wise, a value of -1 is returned and errno is set to indicate the error. ERRORS sam_archive() 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_archive() 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 com- ponent 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), ssum(1), sam_ssum(3) Sun Microsystems Last change: 03 Feb 2002 Introduction to Library Functions sam_cancelstage(3) NAME sam_cancelstage - Cancels a file stage SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsam [ library ... ] #include "/opt/SUNWsamfs/include/lib.h" int sam_cancelstage(const char *path) DESCRIPTION sam_cancelstage() cancels the stage of the file pointed to by path. Only the file owner or superuser can perform this operation on the file. RETURN VALUES Upon successful completion a value of 0 is returned. Other- wise, a value of -1 is returned and errno is set to indicate the error. ERRORS sam_cancelstage() fails if one or more of the following are true: EPERM Caller is not the file owner or superuser. EFAULT buf or path points to an illegal address. EINTR A signal was caught during the sam_cancelstage() function. ELOOP Too many symbolic links were encountered in translating path. EMULTIHOP Components of path require hopping to multiple remote machines and the file system does not allow it. ENAMETOOLONG The length of the path argument exceeds {PATH_MAX}, or the length of a path com- ponent 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 sam_stage(3), sam_stat(3). Sun Microsystems Last change: 05 Nov 2001 Introduction to Library Functions sam_closecat(3) NAME sam_closecat - Closes a catalog handle SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsam [ library ... ] #include "/opt/SUNWsamfs/include/catalog.h" int sam_closecat(int cat_handle); AVAILABILITY 32-bit programs only DESCRIPTION sam_closecat() deallocates the catalog handle indicated by cat_handle. cat_handle is a catalog "handle" obtained from a previous call to sam_opencat(). Deallocation of the cata- log handle ends access to the automated library catalog that it referred to, and makes the catalog handle available for return by subsequent calls to sam_opencat(). RETURN VALUES Upon successful completion, a value of 0 is returned. Oth- erwise, a value of -1 is returned and errno is set to indi- cate the error. ERRORS sam_closecat() fails if one or more of the following error conditions are true: EBADFILE cat_handle is invalid. SEE ALSO sam_getcatalog(3), sam_opencat(3). Sun Microsystems Last change: 05 Nov 2001 Introduction to Library Functions sam_damage(3) NAME sam_damage - Sets damaged attribute on a file or directory SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsam [ library ... ] #include "/opt/SUNWsamfs/include/lib.h" int sam_damage(const char *path, int num_opts, ... ); DESCRIPTION sam_damage() lets you mark archive copies of a file or a directory as damaged, using a Sun StorageTek SAM-FS or Sun SAM-QFS system call. path is the file on which to set the attributes, followed by a sequence of num_opts input charac- ters or options. Individual options are described below. The function marks copies of a file or directory as damaged based on the archive copy number and/or the media type and VSN specified. There are several ways to mark one or more copies as damaged. These ways are as follows: o By copy number o By copy number, media type, and VSN o By copy number and media type o By media type o By media type and VSN If a fatal error is detected when staging an archive copy, that archive copy is marked as damaged. An archive copy that is damaged is not selected for staging. OPTIONS a Rearchives the damaged copy. c copy_no Marks the specified archive copy number as dam- aged. If one or more 'c' options are specified, only those archive copies (1, 2, 3, or 4) are marked as damaged. Specify 1, 2, 3, or 4 for copy_no. Either a "c copy_no" or a "m media" option must be specified. M Marks only metadata as damaged. This includes directories, the segment index, and removable-media files. Regular files are not marked as damaged. If you are marking a directory as damaged, you must specify the "M" option. m media_type Marks all copies from the specified media_type as damaged. For the list of possible media_type specifications, see the mcf(4) man page. Either a "c copy_no" or a "m media" option must be speci- fied. If you specify a "m media" option, you can also specify a "v vsn" option. o Specifies that the file must be online before it is marked as damaged. If the file is offline, the sam_damage function stages the file to disk before deleting any entries. v vsn Marks the archive copies on vsn as damaged. For vsn, specify a volume serial name (VSN). If you specify a "v vsn" option, you must also specify a "m media" option. RETURN VALUES Upon successful completion a value of 0 is returned. Other- wise, a value of -1 is returned and errno is set to indicate the error. ERRORS sam_damage() 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 Argument points to an illegal address. EINTR A signal was caught during the sam_damage() 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 com- ponent 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 damage(1m), mcf(4) Sun Microsystems Last change: 15 May 2007 Introduction to Library Functions sam_devstat(3) NAME sam_devstat, sam_ndevstat - Gets device status SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsam [ library ... ] #include "/opt/SUNWsamfs/include/devstat.h" int sam_devstat(ushort_t eq, struct sam_devstat *buf, size_t bufsize); int sam_ndevstat(ushort_t eq, struct sam_ndevstat *buf, size_t bufsize); DESCRIPTION sam_devstat() and sam_ndevstat() obtain information about the device identified by the equipment number, eq. buf is a pointer to a sam_devstat() or sam_ndevstat() struc- ture into which information is placed concerning the device. bufsize is the length of the user's buffer to which buf points. This should be equal to or greater than sizeof(struct sam_devstat) or sizeof(struct sam_ndevstat). The contents of the structure pointed to by buf include the following members for sam_devstat() : u_short type; /* Media type */ char name[32]; /* Device name */ char vsn[32]; /* VSN of mounted volume, 31 characters */ dstate_t state; /* State - on/ro/idle/off/down */ uint_t status; /* Device status */ uint_t space; /* Space left on device */ uint_t capacity; /* Capacity in blocks */ The contents of the structure pointed to by buf include the following members for sam_ndevstat() : u_short type; /* Media type */ char name[128]; /* Device name */ char vsn[32]; /* VSN of mounted volume, 31 characters */ dstate_t state; /* State - on/ro/idle/off/down */ uint_t status; /* Device status */ uint_t space; /* Space left on device */ uint_t capacity; /* Capacity in blocks */ type The type of the media. Masks for interpreting media type are defined in devstat.h. name The name of the device, such as /dev/rmt/3cbn. vsn The VSN of the mounted volume, if any. This is a null-terminated string with a maximum of 31 char- acters. state The state of the device. This field is an enumerated type defined in devstat.h. status The status of the device. Status bits are defined in the file devstat.h. Also, the library routine sam_devstr(3) is available to translate the numeric status field into a character string as displayed in the Sun StorEdge SAM-FS or Sun SAM-QFS graphical user interfaces and in the Sun StorEdge SAM-FS or Sun SAM-QFS administrative tool samu(1M). space The space left on the device, in blocks. capacity The capacity of the device, in blocks. RETURN VALUES Upon successful completion a value of 0 is returned. Other- wise, a value of -1 is returned and errno is set to indicate the error. ERRORS sam_devstat() or sam_ndevsat() fail if one or more of the following are true: ENODEV The equipment number supplied is not a valid number, or no device is configured with that equipment number. EACCES The program does not have permission to access the Sun StorEdge SAM-FS or Sun SAM-QFS shared memory segment. EINVAL The size of the Sun StorEdge SAM-FS or Sun SAM-QFS shared memory segment is incorrect. You may need to recompile your program with the current version of the Sun StorEdge SAM-FS or Sun SAM-QFS software. ENOENT Access to the Sun StorEdge SAM-FS or Sun SAM-QFS shared memory segment has failed; possibly Sun StorEdge SAM-FS or Sun SAM-QFS is not running. EMFILE The Sun StorEdge SAM-FS or Sun SAM-QFS shared memory segment could not be accessed because the number of shared memory segments attached to the calling process would exceed the system-imposed limit. ENOMEM The available data space is not large enough to accommodate access to the Sun StorEdge SAM-FS or Sun SAM-QFS shared memory segment. E2BIG For sam_devstat() only. The name field of the device was too long to fit in the name field of the sam_dev structure. Use sam_ndevstat(). SEE ALSO samu(1M). sam_devstr(3). Sun Microsystems Last change: 05 Nov 2001 Introduction to Library Functions sam_devstr(3) NAME sam_devstr - Translates numeric device status into character string SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsam [ library ... ] #include "/opt/SUNWsamfs/include/lib.h" char *sam_devstr(uint_t status) DESCRIPTION sam_devstr() translates an unsigned integer, status, into a character status string based on the bits set in status, returning a pointer to the character string. The meanings of the characters in the string returned are as follows: s--------- Volume is being scanned. m--------- If a file system, the file system is mounted. M--------- The device is in maintenance mode. -E-------- Device received an unrecoverable error. -a-------- Device is auditing. If a file system, it is being archived. --l------- Volume has a label. ---I------ Device is in wait-idle mode. ---A------ Device requires operator attention. ----U----- Unload has been requested. -----R---- The device has been requested. ------w--- The device is open for writing. -------o-- The device is open. --------P- The device is positioning (tape only). --------F- All storage slots are occupied (robotic devices only). ---------r Device is ready. If a file system, its disk space is being released. ---------R Device is ready and the volume is read-only. ---------p Device is present. RETURN VALUES A pointer to the character status string is returned. SEE ALSO sam_devstat(3). Sun Microsystems Last change: 05 Nov 2001 Introduction to Library Functions sam_exarchive(3) NAME sam_exarchive - Exchanges archive copies of a file or direc- tory SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsam [ library ... ] #include "/opt/SUNWsamfs/include/lib.h" int sam_exarchive(const char *path, int num_opts, ... ); DESCRIPTION sam_exarchive() lets you exchange archive copies of a file or a directory using a Sun StorageTek SAM-FS or Sun SAM-QFS system call. path is the file whose specified archive copies are to be exchanged, followed by a sequence of num_opts input characters or options. Individual options are described below. OPTIONS c copy_m c copy_n Specifies the copies to be exchanged. The copy_m is exchanged with copy_n. Exactly two 'c' options must be specified. The first copy (copy_m) must have a valid archive entry. M Exarchives metadata only. This includes directories, the segment index, and removable media files. Regular files are not exarchived. If you are exarchiving a directory, you must specify the "M" option. RETURN VALUES Upon successful completion a value of 0 is returned. Other- wise, a value of -1 is returned and errno is set to indicate the error. ERRORS sam_exarchive() 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 Argument points to an illegal address. EINTR A signal was caught during the sam_exarchive() 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 com- ponent 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 exarchive(1m), mcf(4) Sun Microsystems Last change: 15 May 2007 Introduction to Library Functions sam_getcatalog(3) NAME sam_getcatalog - Gets catalog entries SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsam [ library ... ] #include "/opt/SUNWsamfs/include/catalog.h" int sam_getcatalog(int cat_handle, uint start_entry, uint end_entry, struct sam_cat_ent *buf, size_t entbufsize); AVAILABILITY 32-bit programs only DESCRIPTION sam_getcatalog() obtains a range of entries from the catalog of an automated library or the historian. The catalog from which entries will be obtained is indicated by cat_handle. cat_handle is similar to a file descriptor, and is returned from a previous call to sam_opencat(). The range of entries is indicated by start_entry and end_entry. start_entry must be less than or equal to end_entry, and must be in the range of valid slot numbers for the automated library (or his- torian). buf is a pointer to an array of sam_cat_ent struc- tures, into which the catalog entry information is placed. This array should be large enough to hold the number of entries requested. entbufsize is the size of a single sam_cat_ent structure, usually indicated by sizeof(struct sam_cat_ent). The contents of a sam_cat_ent structure include the follow- ing members: /* catalog table entry */ uint_t type; /* OBSOLETE */ uint_t status; /* Catalog entry status */ char media[4]; /* Media type */ char vsn[32]; /* VSN */ int access; /* Count of accesses */ uint_t capacity; /* Capacity of volume */ uint_t space; /* Space left on volume */ int ptoc_fwa; /* First word address of PTOC */ int reserved[3]; /* Reserved space */ time_t modification_time;/* Last modification time */ time_t mount_time; /* Last mount time */ uchar_t bar_code[BARCODE_LEN + 1];/* Bar code (zero filled) */ RETURN VALUES Upon successful completion the number of catalog entries obtained is returned. Otherwise, a value of -1 is returned and errno is set to indicate the error. ERRORS sam_getcatalog() fails if one or more of the following are true: EBADF The catalog handle provided is invalid. EFAULT buf is an invalid address. EOVERFLOW The catalog library software returned more information than was requested. ENOENT This is no longer an active catalog. EINVAL The buffer size provided is invalid, or start_entry or end_entry is invalid. (Either start_entry is less than zero, end_entry is greater than the number of entries in the catalog, or start_entry is greater than end_entry.) SEE ALSO sam_closecat(3), sam_opencat(3). Sun Microsystems Last change: 05 Nov 2001 Introduction to Library Functions sam_stat(3) NAME sam_stat, sam_lstat, sam_segment_stat - Gets file or segment status SYNOPSIS cc [flag ...] file ... -L/opt/SUNWsamfs/lib -R/opt/SUNWsamfs/lib -lsam [library ...] #include "/opt/SUNWsamfs/include/stat.h" int sam_stat(const char *path, struct sam_stat *buf, size_t bufsize); int sam_lstat(const char *path, struct sam_stat *buf, size_t bufsize); int sam_segment_stat(const char *path, struct sam_stat *buf, size_t bufsize); AVAILABILITY SUNWqfs SUNWsamfs DESCRIPTION The sam_stat() function returns file system attributes for the file to which path points. The sam_segment_stat() function works with segmented files. It returns attributes for the file segments to which path points. The sam_lstat() function returns file attributes similar to sam_stat(). The difference is that if file is a symbolic link, sam_lstat() returns information about the link, while sam_stat() returns information about the file or the file's segments that the link references. If these functions succeed, they write file attributes to the structure, or to the array of structures, to which buf points. If they are returning information about a segmented file, they write information about the first file segment to the first structure in the array of structures. They write information about the second file segment to the second structure in the array of structures, etc. Note that when sam_stat() and sam_lstat() are executed on a segmented file, the functions return information about the index inode. The sam_stat and sam_lstat functions are supported in Sun StorEdge QFS, Sun StorEdge SAM-FS, and Sun SAM-QFS environments. The sam_segment_stat function is supported in Sun StorEdge SAM-FS and Sun SAM-QFS environments. OPTIONS These functions accept the following arguments: path Specifies the path to the file. This is the file or segmented file for which the file status is to be obtained. Read, write, or execute permission of the named file is not required, but all directories listed in the path leading to the file must be searchable. buf Specifies a pointer to a structure into which information is placed concerning the file. The functions use one sam_stat structure from this argument for each single file or file segment. The length of buf, in bytes, must be sized as follows: bytes = number_of_segments * sizeof(struct sam_stat) The number_of_segments is 1 for a nonsegmented file (used by sam_stat and sam_lstat). The number_of_segments is greater than 1 for a segmented file (used by sam_segment_stat). For an unsegmented file, buf must be a sam_struct structure. For a segmented file, buf must be an array of sam_struct structures. bufsize Specifies the length of the user's buffer, in bytes, to which buf points. STRUCTURE CONTENTS Table 1 and Table 2 show the content of the structure pointed to by buf. TABLE 1. Members of struct sam_stat That Contain POSIX Standard File Attributes Data Type Field Name Description ulong_t st_mode File mode (see mknod(2) ulong_t st_ino Inode number ulong_t st_dev ID of device containing the file ulong_t st_nlink Number of links ulong_t st_uid Numeric user ID of the file's owner ulong_t st_gid Numeric group ID of the file's owner u_longlong_t st_size File size in bytes time_t st_atime Time of last access time_t st_mtime Time of last data modification time_t st_ctime Time of last file status change The following list describes Table 1's fields in more detail. st_mode The mode of the file as described in mknod(2). In addition to the modes described in mknod(2), the mode of a file may also be S_IFLNK if the file is a symbolic link. Note that S_IFLNK can be returned only by sam_lstat(). st_ino This field uniquely identifies the file in a given file system. The pair st_ino and st_dev uniquely identifies regular files. st_dev This field uniquely identifies the file system that contains the file. st_nlink This field should be used only by administrative commands. st_uid The numeric user ID of the file's owner. st_gid The numeric group ID of the file's owner. st_size For regular files, this is the address of the end of the file. st_atime Time when file data was last accessed. Changed by the following functions: creat, mknod, pipe, utime, and read. st_mtime Time when data was last modified. Changed by the following functions: creat, mknod, pipe, utime, and write. st_ctime Time when file status was last changed. Changed by the following functions: chmod, chown, creat, link, mknod, pipe, unlink, utime, and write. TABLE 2. Members of struct sam_stat That Contain Sun StorEdge QFS, Sun StorEdge SAM-FS, and Sun SAM-QFS File Attributes Data Type Field Name Description uint_t attr File attributes time_t attribute_time Time attributes last changed time_t creation_time Time inode created time_t residence_time Time file changed residence struct sam_copy_s copy[MAX_ARCHIVE] Array of archive copy information uchar_t cs_algo Checksum algorithm indicator uchar_t flags Flags: staging, stage err, etc. uchar_t stripe_width Stripe width set by setfa -s uchar_t stripe_group Stripe group set by setfa -g ulong_t gen Inode generation number ulong_t partial_size Partial size in kilobytes dev_t rdev ID of device if S_IFBLK or S_IFCHR u_longlong_t st_blocks Block count in 512 byte blocks ulong_t segment_size Segment size in megabytes ulong_t segment_number Number of this segment uint_t stage_ahead Number of segment to stage ahead uint_t admin_id admin ID; inherited from directory uint_t allocahead Allocate ahead size set by setfa -A u_longlong_t csum_val[2] 128 checksum value The following list describes Table 2's fields in more detail. attr Attributes assigned to the file by Sun StorEdge QFS, Sun StorEdge SAM-FS, and Sun SAM-QFS functions and operations. attribute_time Time when the Sun StorEdge QFS, Sun StorEdge SAM-FS, and Sun SAM-QFS attributes last changed. Changed by the following functions: sam_archive, sam_release, and sam_stage. Also changed by the automatic archive, release, and stage operations. creation_time Time when the inode was created for the file. residence_time Time when the file changed residency. Changed by the release and stage operations. cs_algo Indicates the algorithm that is used when calculating the data verification value (checksum) for the file. For more information, see ssum(1). flags Flags containing miscellaneous additional information about the file. Includes a bit that indicates that a stage is pending or is in progress on the file. Also includes a bit that indicates that the last attempt to stage the file failed. gen The inode generation number. RETURN VALUES Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and errno is set to indicate the error. ERRORS The sam_stat() and sam_lstat() functions fail if one or more of the following are true: EACCES Search permission is denied for a component of the path prefix. EFAULT Either buf or path points to an illegal address. EINTR A signal was caught during sam_stat() or sam_lstat() function processing. ELOOP Too many symbolic links were encountered in translating path. EMULTIHOP Components of path require hopping to multiple remote machines and the file system does not allow it. ENAMETOOLONG The length of the path argument exceeds {PATH_MAX}, or the length of path 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. EOVERFLOW A component is too large to store in the structure to which buf points. EXAMPLES This example uses sam_segment_stat to obtain the status of a segmented file. struct sam_stat file_info; struct sam_stat *data_seg_info_ptr; int number_of_data_segments; int result; /* * Initialize file_info to be all zero bits: */ memset((void *) &file_info, 0, sizeof(struct sam_stat)); /* * Stat the file using the regular sam_stat function: */ result = sam_stat(path, &file_info, sizeof(struct sam_stat)); if (result != 0) { fprintf(stderr, "Error failed to sam stat the file, %s.\n", path); exit -70; } if (SS_ISSEGMENT_F(file_info.attr)) { /* * File is segmented, how many data segments does it have? */ /* * Determine how many complete (full) segments it has: */ number_of_data_segments = file_info.st_size / (file_info.segment_size * 1048576); /* * Determine if it has one data segment that isn't "full": */ if (file_info.st_size > number_of_data_segments * file_info.segment_size * 1048576) { number_of_data_segments++; } } else { /* * File isn't segmented */ number_of_data_segments = 1; } /* * Allocate enough memory to hold all of the stat information for each * data segment: */ data_seg_info_ptr = (struct sam_stat *) malloc(number_of_data_segments * sizeof(struct sam_stat)); if (data_seg_info_ptr == NULL) { fprintf(stderr, "Error failed to allocate memory for data segment stat operation.\n"); exit -80; } /* * Initialize file_info to be all zero bits: */ memset((void *) data_seg_info_ptr, 0, number_of_data_segments * sizeof(struct sam_stat)); if (SS_ISSEGMENT_F(file_info.attr)) { /* * Use sam_segment_stat to get the stat information for all of the * data segments of the file. */ result = sam_segment_stat(path, data_seg_info_ptr, number_of_data_segments * sizeof(struct sam_stat)); } else { /* * File is not segmented, just use the stat information from the * sam_stat call */ memcpy((void *) data_seg_info_ptr, (void *)file_info, sizeof(struct sam_stat)); } if (!SS_ISSEGMENT_F(file_info.attr)) { number_of_data_segments = 1; data_seg_info_ptr = &file_info_ptr; } /* * data_seg_info_ptr now points to an array of sam_stat structures. * There is one sam_stat structure for each data segment and they are * indexed 0 through number_of_data_segments - 1. * * Do not forget to deallocate the memory buffer pointed to by * data_seg_info_ptr using free. */ SEE ALSO ssum(1). mknod(2), stat(2). Sun Microsystems Last change: 05 Nov 2001 Introduction to Library Functions sam_mig_create_file(3) NAME sam_mig_create_file - Creates an offline Sun StorageTek SAM-QFS file from foreign media SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsamut [ library ... ] #include "/opt/SUNWsamfs/include/mig.h" #include "/opt/SUNWsamfs/include/stat.h" int sam_mig_create_file(char *path, struct sam_stat *buf); AVAILABILITY SUNWsamfs DESCRIPTION sam_mig_create_file() creates an offline Sun StorEdge SAM-FS or Sun SAM-QFS file from a foreign (non- Sun StorEdge SAM-FS or Sun SAM-QFS) media. sam_mig_create_file() creates an offline file using information supplied by a foreign data migration program. The information used to identify the location of the file is stored in the file inode in the archive record. Note that the program calling this function is responsible for creating all directories in the path before calling the function. path is the pathname to the file to be created. It may be an absolute or relative pathname but must be no longer than PATH_MAX (see the /usr/include/limits.h file). buf is a sam_stat structure (see sam_stat(3)). The follow- ing fields of this struct are ignored: st_ino, st_dev, st_rdev, st_nlink, st_blksize, st_blocks, cs_algo, flags, gen, residence_time, and attribute_time. These members in the sam_stat structure must be filled in: ulong_t st_mode /* File mode (see mknod(2)) */ ulong_t st_uid /* User ID of the file's owner */ ulong_t st_gid /* Group ID of the file's owner */ u_longlong_t st_size /* File size in bytes */ ulong_t st_atime /* Time of last access */ ulong_t st_ctime /* Time of last file status change */ ulong_t st_mtime /* Time of last data modification */ These members in the sam_copy_s structure for the desired copy (copy[] part of the sam_stat structure) must be filled in: u_longlong_t position; /* Any 8 bytes */ time_t creation_time; /* The time the archive file is created */ uint_t offset; /* Any 4 bytes */ char vsn[32]; /* Any 31 characters */ char media[2]; /* 2nd character of media type (must be 'z') */ char media[3]; /* 3rd character of media type */ /* (must be a digit or lowercase alpha)*/ position Any 8 bytes that the 3rd party media program requires. creation_time This is the time that the archive was made. If creation_time is zero, it will be set to the value of time(). offset Any 4 bytes that the 3rd party media program requires. vsn This is any 31 characters. The 32nd character must be a zero byte. Other utilities may require this to be a valid VSN. media The second character of the two character media type. If this field is zero, then this copy does not contain any archive information and will be ignored. At least one of the entries must contain information. Upon succesful creation of a file a value of 0 is returned. Otherwise, a value of -1 is returned and errno is set to indicate the error. FILES /opt/SUNWsamfs/migkit/mig_build_cd.c The example Migration Toolkit program. /etc/opt/SUNWsamfs/mcf The configuration file for Sun StorEdge SAM-FS and Sun SAM-QFS file systems. SEE ALSO sam_stat(3). Sun Microsystems Last change: 09 May 2007 Introduction to Library Functions sam_mig_mount_media(3) NAME sam_mig_mount_media - Queues mount request for media SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsamut [ library ... ] #include "/opt/SUNWsamfs/include/mig.h" char *sam_mig_mount_media(char *vsn, char *media); AVAILABILITY SUNWsamfs DESCRIPTION sam_mig_mount_media() queues a mount request for the media with the volume serial number or barcode vsn and media type media. sam_mig_mount_media() returns a pointer to the path- name of the device where the media is mounted. A null pointer will be returned if the media cannot be mounted. This pointer will actually be a symbolic link to the device. The symbolic link will be deleted when the reservation for the device has expired or is released with sam_mig_release_device. The daemon will wait for the device to close before releasing the device. RETURN VALUES Upon succesful completion a pointer to the pathname of the device is returned. Otherwise, a value of 0 is returned and errno is set to indicate the error. FILES /etc/opt/SUNWsamfs/mcf The configuration file for Sun StorEdge SAM-FS or SAM-QFS NOTE Note that the media type passed to sam_mig_mount_media must be the media type as shown in the catalog entry for the VSN. It must not begin with "z". SEE ALSO mcf(4) Sun Microsystems Last change: 05 Nov 2001 Introduction to Library Functions sam_mig_rearchive(3) NAME sam_mig_rearchive - Sets rearchive flag on files residing on foreign media SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsamut [ library ... ] #include "/opt/SUNWsamfs/include/mig.h" int sam_mig_rearchive(char *mount_point, char **vsns, char *media); AVAILABILITY SUNWsamfs DESCRIPTION sam_mig_rearchive() is a routine that traverses a file sys- tem and marks archive files residing on a foreign medium as needing to be rearchived. This allows a site the ability to migrate files from the foreign media to Sun StorEdge SAM-FS or Sun SAM-QFS media in a controlled fashion. mount_point is the mount point of the Sun StorEdge SAM-FS or Sun SAM-QFS file system to scan. vsns is a NULL terminated list pointing to the VSNs to be searched. media is the two character string containing the foreign media type. RETURN VALUES Upon succesful initialization a value of 0 is returned. Otherwise, a value of 1 is returned and errno is set to indicate the error. FILES /opt/SUNWsamfs/migkit/mig_rearch.c The example Migration Toolkit program. /etc/opt/SUNWsamfs/mcf The configuration file for Sun StorEdge SAM-FS and Sun SAM-QFS file systems. SEE ALSO mcf(4). Sun Microsystems Last change: 05 Nov 2001 Introduction to Library Functions sam_mig_release_device(3) NAME sam_mig_release_device - Releases a device SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsamut [ library ... ] #include "/opt/SUNWsamfs/include/mig.h" int sam_mig_release_device(char *device); AVAILABILITY SUNWsamfs DESCRIPTION sam_mig_release_device() releases the reservation for the device returned from sam_mig_mount_media. The drive will enter the pool of available drives and the media will be unloaded when the drive is needed or the idle_unload time has expired (see defaults.conf(4)). RETURN VALUES Upon succesful completion a value of 0 is returned. Other- wise, a value of -1 is returned and errno is set to indicate the error. FILES /etc/opt/SUNWsamfs/mcf The configuration file for Sun StorEdge SAM-FS and Sun SAM-QFS file systems. SEE ALSO defaults.conf(4). Sun Microsystems Last change: 05 Nov 2001 Introduction to Library Functions sam_mig_stage_end(3) NAME sam_mig_stage_end - Completes staging function for foreign data migration program SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsamut [ library ... ] #include "/opt/SUNWsamfs/include/mig.h" int sam_mig_stage_end(tp_stage_t *stage_req, int error); AVAILABILITY SUNWsamfs DESCRIPTION sam_mig_stage_end() is called when the foreign data migra- tion program has finished the stage or detected an error after sam_mig_stage_file has been called without error. stage_req is the number of this stage request. error is the number of the error to pass back to the file system. A 0 indicates no error. RETURN VALUES Upon succesful completion a value of 0 is returned. FILES /opt/SUNWsamfs/migkit/mig_cd.c The example Migration Toolkit program. /etc/opt/SUNWsamfs/mcf The configuration file for Sun StorEdge SAM-FS and Sun SAM-QFS file systems. SEE ALSO sam_mig_stage_file(3). Sun Microsystems Last change: 05 Nov 2001 Introduction to Library Functions sam_mig_stage_error(3) NAME sam_mig_stage_error - Passes errors to the file system SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsamut [ library ... ] #include "/opt/SUNWsamfs/include/mig.h" int sam_mig_stage_error(tp_stage_t *stage_req, int error); AVAILABILITY SUNWsamfs DESCRIPTION This function is used to pass error to the file system for the stage request associated with stage_req. This ends all activity for this stage request. RETURN VALUES Upon succesful completion a value of 0 is returned. FILES /opt/SUNWsamfs/migkit/mig_cd.c The example Migration Toolkit program. /etc/opt/SUNWsamfs/mcf The configuration file for Sun StorEdge SAM-FS and Sun SAM-QFS file systems. SEE ALSO mcf(4). Sun Microsystems Last change: 05 Nov 2001 Introduction to Library Functions sam_mig_stage_file(3) NAME sam_mig_stage_file - Stages function from foreign data migration program SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsamut [ library ... ] #include "/opt/SUNWsamfs/include/mig.h" int sam_mig_stage_file(tp_stage_t *stage_req); AVAILABILITY SUNWsamfs DESCRIPTION sam_mig_stage_file() is called when the foreign data migra- tion program is ready to start staging the data for the stage request associated with stage_req. RETURN VALUES sam_mig_stage_file() returns a 0 if the file system is ready for usage. Otherwise, a value of -1 is returned and ends all activity for this stage. errno is set to indicate the error. FILES /opt/SUNWsamfs/migkit/mig_cd.c The example Migration Toolkit program. /etc/opt/SUNWsamfs/mcf The configuration file for Sun StorEdge SAM-FS and Sun SAM-QFS file systems. SEE ALSO mcf(4). Sun Microsystems Last change: 05 Nov 2001 Introduction to Library Functions sam_mig_stage_write(3) NAME sam_mig_stage_write - Stages data from foreign data migra- tion program SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsamut [ library ... ] #include "/opt/SUNWsamfs/include/mig.h" int sam_mig_stage_write(tp_stage_t *stage_req, char *buffer, int len, offset_t offset); AVAILABILITY SUNWsamfs DESCRIPTION sam_mig_stage_write() passes data from the foreign data migration program to the file system for the stage associ- ated with stage_req (see sam_mig_stage_file(3)). stage_req is the number of this stage request. buffer is a pointer to the data that needs to be transferred. len is the number of bytes of data to transfer. offset is the offset from the beginning of this stage request. This is not the offset from the beginning of the file (keep in mind stage_never). RETURN VALUES sam_mig_stage_write returns the actual number of bytes writ- ten. Otherwise, a value of -1 is returned. If an error is returned, sam_mig_stage_end should still be called. The only function allowed on stage_req after an error is sam_mig_stage_end. FILES /opt/SUNWsamfs/migkit/mig_cd.c The example Migration Toolkit program /etc/opt/SUNWsamfs/mcf The configuration file for Sun StorEdge SAM-FS or Sun SAM-QFS SEE ALSO sam_mig_stage_end(3), sam_mig_stage_file(3) Sun Microsystems Last change: 05 Nov 2001 Introduction to Library Functions sam_opencat(3) NAME sam_opencat - Accesses an automated library's catalog to read entries SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsam [ library ... ] #include "/opt/SUNWsamfs/include/catalog.h" int sam_opencat(const char *path, struct sam_cat_tbl *buf, size_t bufsize); AVAILABILITY 32-bit programs only DESCRIPTION sam_opencat() initiates access to the automated library catalog pointed to by path. The string which path points to is limited to 127 characters. It returns a sam_cat_tbl structure in the area pointed to by buf . bufsize is the length of the user's buffer to which buf points. This should be equal to or greater than sizeof(struct sam_cat_tbl). The user may have access to at most MAX_CAT catalogs at any one time. The contents of a sam_cat_tbl structure include the follow- ing members: /* catalog table */ time_t audit_time; /* Audit time */ int version; /* Catalog version number */ int count; /* Number of slots */ char media[4]; /* Media type, if entire catalog is one */ Following the call to sam_opencat(), entries in the library catalog are obtained using sam_getcatalog(). RETURN VALUES Upon successful completion, a catalog "handle" is returned, which is an integer equal to or greater than zero. This "handle" is used on subsequent calls to sam_getcatalog() to specify the catalog to access, and is also used by sam_closecat() to deallocate the "handle" and end access to the catalog. If the call to sam_opencat() fails, a value of -1 is returned and errno is set to indicate the error. ERRORS sam_opencat() fails if one or more of the following error conditions are true: EMFILE The user already has access to MAX_CAT catalogs , or the process has too many open files. EINVAL bufsize is set to an invalid value, or either path or buf is a null pointer. ER_UNABLE_TO_INIT_CATALOG This process was unable to initialize the catalog data. ENOENT There is no active catalog file with the name given. SEE ALSO sam_closecat(3), sam_getcatalog(3) Sun Microsystems Last change: 05 Nov 2001 Introduction to Library Functions sam_readrminfo(3) NAME sam_readrminfo - Gets removable media file status SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -R/opt/SUNWsamfs/lib -lsam [ library ... ] #include "/opt/SUNWsamfs/include/rminfo.h" int sam_readrminfo(const char *path, struct sam_rminfo *buf, size_t bufsize); DESCRIPTION sam_readrminfo() returns information about a removable media file. The removable media file is pointed to by path. buf is a pointer to a sam_rminfo() structure into which information is placed concerning the file. bufsize is the length of the user's buffer to which buf points. This should be equal to or greater than sizeof(struct sam_rminfo). The maximum number of overflow VSNs is 256. The following macro can be used to calculate the size of the sam_rminfo structure for n VSNs. #define SAM_RMINFO_SIZE(n) (sizeof(struct sam_rminfo) + ((n) - 1) * sizeof(struct sam_section)) The contents of the structure pointed to by buf is docu- mented in sam_request(3). RETURN VALUES Upon successful completion a value of 0 is returned. Other- wise, a value of -1 is returned and errno is set to indicate the error. ERRORS sam_readrminfo() fails if one or more of the following are true: EACCES Search permission is denied for a com- ponent of the path prefix. EFAULT buf or path points to an illegal address. EINTR A signal was caught during the sam_readrminfo() function. ELOOP Too many symbolic links were encountered in translating path. EMULTIHOP Components of path require hopping to multiple remote machines and the file system does not allow it. ENAMETOOLONG The length of the path argument exceeds {PATH_MAX}, or the length of a path com- ponent 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. EOVERFLOW A component is too large to store in the structure pointed to by buf. SEE ALSO sam_request(3) Sun Microsystems Last change: 05 Nov 2001 Introduction to Library Functions sam_rearch(3) NAME sam_rearch - Sets rearchive attributes on a file or direc- tory SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsam [ library ... ] #include "/opt/SUNWsamfs/include/lib.h" int sam_rearch(const char *path, int num_opts, ... ); DESCRIPTION sam_rearch() sets rearchive attributes on a file or direc- tory using a Sun StorageTek SAM-FS or Sun SAM-QFS system call. path is the file on which to set the attributes, fol- lowed by a sequence of num_opts input characters or options. Individual options are described below. OPTIONS c copy_no Specifies the archive copy number. If one or more 'c' options are specified, only those archive copies (1, 2, 3 or 4) are marked. If not specified, the default is all copies only in the case that media type and VSN are specified, using the "m media" option and "v vsn" option. M Rearchives metadata only. This includes directories, the segment index, and removable media files. Regular files and symbolic links are not rearchived. m media Specifies the media type. If specified, archive copies on the specified media are marked. This option must be specified in conjunction with the "v vsn" option. For more information on media types, see the mcf(4) man page. o Requires the file to be online before its archive entry is rearchived. If the file is offline, the function stages the file onto disk before rearchiving any entries. v vsn Marks archive copies on VSN vsn for rearchiving. This option must be specified in conjunction with the "m media" option. RETURN VALUES Upon successful completion a value of 0 is returned. Other- wise, a value of -1 is returned and errno is set to indicate the error. ERRORS sam_rearch() 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 Argument points to an illegal address. EINTR A signal was caught during the sam_rearch() 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 com- ponent 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 rearch(1m), mcf(4) Sun Microsystems Last change: 15 May 2007 Introduction to Library Functions sam_release(3) NAME sam_release - Sets release attributes on a file or directory SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsam [ library ... ] #include "/opt/SUNWsamfs/include/lib.h" int sam_release(const char *path, const char *ops); DESCRIPTION sam_release() sets release attributes on a file or directory using a Sun StorEdge 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: "dn". Individual options are described below. OPTIONS a Set the attribute that specifies that a file's disk space be released when at least one archive copy of the file exists. Not valid with n. d Return the release attributes on the file to the default, i.e. the file space is released according to archiver rules or as needed by the releaser. When this option is specified, the attributes are reset to the default. If the partial attribute is reset, all blocks are released for an offline regular file. If it is used, it should be the first character in the string. i Specifies that the file's disk space be released immediately. This will occur if the file is currently not staging, has at least one archive copy, and has some data in it. n Specifies that the disk space for this file never be released. Only the super-user can set this attribute on a file. p Set the partial attribute on the file so that, when the file's disk space is released, the first portion of that disk space will be retained. Not valid with sam_release n option. Also not valid with either of the checksum g (generate) or u (use) attributes. (See ssum(1) or sam_ssum(3)). If the partial attribute is set when the file is off- line, the partial blocks are not on the disk and the entire file will be staged if accessed. The sam_stage p attribute can be used to stage the partial blocks to the disk. s n Set the partial attribute on the file so that, when the file's disk space is released, the first n kilobytes of that disk space will be retained. Not valid with release -n. Also not valid with either of the checksum generate or use attributes (ssum -g or ssum -u). The minimum value is 8 kbytes and the maximum value is the maxpartial value set for this file system by the mount command (see mount_samfs (1M)). NOTE: Even though only a portion of the file is retained on disk, the amount of disk space consumed is equal to one DAU. So, for example, if the partial size is set to 16K and the DAU size is 256K, even though only 16K of data remains after a partial release, the actual disk space used is 256K. RETURN VALUES Upon successful completion a value of 0 is returned. Other- wise, a value of -1 is returned and errno is set to indicate the error. ERRORS sam_release() 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_release() function. ELOOP Too many symbolic links were encountered in translating path. EMULTIHOP Components of path require hopping to multiple remote machines and the file system does not allow it. ENAMETOOLONG The length of the path argument exceeds {PATH_MAX}, or the length of a path com- ponent 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. ENOTSUP License does not support option. SEE ALSO release(1), ssum(1). sam_ssum(3). Sun Microsystems Last change: 01 Oct 2004 Introduction to Library Functions sam_request(3) NAME sam_request - Creates a removable media file SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -R/opt/SUNWsamfs/lib -lsam [ library ... ] #include "/opt/SUNWsamfs/include/rminfo.h" int sam_request(const char *path, struct sam_rminfo *buf, size_t bufsize); DESCRIPTION sam_request() creates a removable media file allowing access to either tape or optical disk. The removable media file is pointed to by path. buf is a pointer to a sam_rminfo() structure into which information is placed concerning the file. bufsize is the length of the user's buffer to which buf points. This should be equal to or greater than sizeof(struct sam_rminfo). The maximum number of overflow VSNs is 256. The following macro can be used to calculate the size of the sam_rminfo structure for n VSNs. #define SAM_RMINFO_SIZE(n) (sizeof(struct sam_rminfo) + ((n) - 1) * sizeof(struct sam_section)) The contents of the structure pointed to by buf include the following members: /* POSIX rminfo structure. */ ushort_t flags; /* File mode (see mknod(2)) */ char media[4]; /* Media type */ ulong_t creation_time; /* Creation time of removable media file */ uint_t block_size; /* Block size of file in bytes */ U_longlong_t position; /* Position of file on the removable media */ U_longlong_t required_size; /* Required size for optical only */ /* optical information only. */ char file_id[32]; /* File identifier */ int version; /* Version number */ char owner_id[32]; /* Owner identifier */ char group_id[32]; /* Group identifier */ char info[160]; /* Information */ /* all media information. */ short n_vsns; /* Number of vsns containing file */ short c_vsn; /* Current vsn ordinal -- returned */ struct sam_section section[1]; /* VSN array - n_vsns entries */ flags The access flags for the file. RI_blockio uses block I/O for data transfers. Each request buffer is a block on the device. RI_bufio uses buffered I/O for data transfers. The block size is defined by block_size. RI_foreign uses block I/O for data transfers. The tape is not written by Sun SAM-FS or Sun SAM-QFS, is barcoded, write protected, and is opened for read access only. media The left adjusted string which identifies the media type. See mcf(4). creation_time Specifies the time the file was created. This value is not used on entry. block_size The length of the block in bytes. The block_size is set in the volume labels when the removable media is labeled. This value is returned. position This field can be set by superuser to specify an initial starting position for the file. required_size This size in bytes may be specified. If set, this space must be left on the removable media. file_id The file's ID. It is written into the optical file label. version The version number of the file. It is returned. owner_id The file's owner ID. It is written into the opti- cal file label. group_id The file's group ID. It is written into the opti- cal file label. info The file's optional information field. It is written into the optical file label by . n_vsns Specified the number of removable media cartridges containing the file. c_vsn Specifies the current removable media ordinal. sam_section Specifies the array of removable media cartridges. The contents of the sam_section structure includes the following members: /* POSIX sam_section structure. */ char vsn[32]; /* Volume serial name */ U_longlong_t length; /* Length of this section in bytes */ U_longlong_t position; /* Position of this section */ U_longlong_t offset; /* Byte offset of this section */ RETURN VALUES Upon successful completion a value of 0 is returned. Other- wise, a value of -1 is returned and errno is set to indicate the error. ERRORS sam_request() fails if one or more of the following are true: EACCES Search permission is denied for a com- ponent of the path prefix. EFAULT buf or path points to an illegal address. EINTR A signal was caught during the sam_request() function. ELOOP Too many symbolic links were encountered in translating path. EMULTIHOP Components of path require hopping to multiple remote machines and the file system does not allow it. ENAMETOOLONG The length of the path argument exceeds {PATH_MAX}, or the length of a path com- ponent 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. EOVERFLOW A component is too large to store in the structure pointed to by buf. ENOTSUP License does not support foreign tapes. SEE ALSO request(1). mcf(4). Sun Microsystems Last change: 01 Oct 2004 Introduction to Library Functions sam_restore_copy(3) NAME sam_restore_copy - Creates an archive copy for a Sun StorEdge SAM-FS or a Sun SAM-QFS file SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsamut [ library ... ] #include "/opt/SUNWsamfs/include/stat.h" int sam_restore_copy(const char *path, int copy, struct sam_stat *buf, size_t bufsize, struct sam_section *vbuf, size_t vbufsize); DESCRIPTION The sam_restore_copy() library routine creates an archive copy for an existing Sun StorEdge SAM-FS or Sun SAM-QFS file. The file must already exist and the archive copy must not exist. The sam_restore_copy() library routine creates an archive copy using information supplied by the user and obtained from a source such as the archiver.log. This library routine accepts the following arguments: path The path name to the file where the archive copy is being created. It may be an absolute or relative path name, but it must be no longer than PATH_MAX (see the /usr/include/limits.h file). copy The copy number (0, 1, 2, or 3) of the archive copy that is being created. buf A sam_stat structure. See sam_stat(3). bufsize The size of the sam_stat structure. See sam_stat(3). vbuf A sam_section structure for the array of VSNs if the archive copy overflowed volumes, that is, n_vsns > 1. If n_vsns = 1, vbuf should be set to NULL. See sam_stat(3). vbufsize The size of the sam_section structure. If n_vsns = 1, vbufsize should be set to 0. See sam_stat(3). The following members in the sam_stat structure must exist. All other fields are ignored. ulong_t st_mode /* File mode (see mknod(2)) */ ulong_t st_uid /* User ID of the file's owner */ ulong_t st_gid /* Group ID of the file's owner */ u_longlong_t st_size /* File size in bytes */ ulong_t st_atime /* Time of last access */ ulong_t st_ctime /* Time of last file status change */ ulong_t st_mtime /* Time of last data modification */ The following members in the sam_copy_s structure must exist for the copy. All other fields are ignored. u_longlong_t position; /* Position of the file on the media. */ time_t creation_time; /* Time the archive copy was created */ uint_t offset; /* Location of the copy in the archive file */ short n_vsns; /* Number of volumes used by the archive */ char media[4]; /* Two character media type. */ char vsn[32]; /* Volume serial name of the media volume */ The preceding fields have the following meaning: position The position of the file recorded on the media. creation_time This is the time that the archive was made. If creation_time is zero, it is set to the value of time(). offset The location of the copy in the archive file in units of 512 bytes. n_vsns The number of volumes that this copy spans. vsn The volume serial name of the cartridge where the file resides. media The two-character media type. For example, the media type for DLT tape is lt. See mcf(4). RETURN VALUES Upon succesful creation of a file, a value of 0 is returned. Otherwise, a negative value is returned and errno is set to indicate the error. The possible return values are: -1 user is not root -2 invalid copy number -3 invalid VSN -4 file does not exist -5 file open failed -6 uid and gid do not match those for the existing file -7 invalid VSN for this copy -8 multiple copies but vbufsize incorrect -9 media type invalid -10 copy restore failed for some other reason FILES /etc/opt/SUNWsamfs/mcf The configuration file for Sun StorEdge SAM-FS or Sun SAM-QFS file systems. SEE ALSO sam_restore_file(3), sam_stat(3). mcf(4). Sun Microsystems Last change: 24 Jan 2002 Introduction to Library Functions sam_restore_file(3) NAME sam_restore_file - Creates an offline Sun StorEdge SAM-FS file. SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsamut [ library ... ] #include "/opt/SUNWsamfs/include/stat.h" int sam_restore_file(const char *path, struct sam_stat *buf, size_t bufsize); DESCRIPTION sam_restore_file() creates an offline file in a Sun StorEdge SAM-FS or Sun SAM-QFS file system. sam_restore_file() creates an offline file using information supplied by the user and obtained from a source such as the archiver.log file. The file must not exist. Note that the program calling this function is responsible for creating all directories in the path before calling the function. path is the pathname to the file to be created. It may be an absolute or relative pathname but must be no longer than PATH_MAX (see the /usr/include/limits.h file). buf is a sam_stat(3) structure (see sam_stat(3)). bufsize is the size of the sam_stat(3) structure (see sam_stat(3)). The following members in the sam_stat(3) structure must exist. All other fields are ignored. ulong_t st_mode /* File mode (see mknod(2)) */ ulong_t st_uid /* User ID of the file's owner */ ulong_t st_gid /* Group ID of the file's owner */ u_longlong_t st_size /* File size in bytes */ ulong_t st_atime /* Time of last access */ ulong_t st_ctime /* Time of last file status change */ ulong_t st_mtime /* Time of last data modification */ The following members in the sam_copy_s structure must exist for all copies, if any. All other fields are ignored. char media[4]; /* Two character media type. */ long_long position; /* Position of the file on the media. */ time_t creation_time; /* Time the archive copy was created */ char vsn[32]; /* Volume serial name of the media */ position The position of the file recorded on the media. creation_time This is the time that the archive was made. If creation_time is zero, it will be set to the value of time(). vsn The volume serial name of the cartridge where the file resides. media The two character media type. See mcf(4). For example, the media type for DLT tape is lt. RETURN VALUES Upon succesful creation of a file a value of 0 is returned. Otherwise, a negative value is returned and errno is set to indicate the error. The possible return values are: -1 user is not root -2 invalid media type -3 invalid VSN -5 file does not exist -6 restore failed for some other reason FILES sam_stat(3). Sun Microsystems Last change: 28 Jan 2002 Introduction to Library Functions sam_segment(3) NAME sam_segment - Sets segment attributes on a file or directory SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsam [ library ... ] #include "/opt/SUNWsamfs/include/lib.h" int sam_segment(const char *path, const char *ops); DESCRIPTION sam_segment() sets segment attributes on a file or directory using a Sun StorEdge SAM-FS or a Sun SAM-QFS system call. If a file is segmented, it is archived and staged in segment size chunks. sam_segment() is not supported on a Sun SAM-QFS shared file system. path is the file on which to set the attributes. ops is the character string of options, for example: "dl104857600". Individual options are described below. OPTIONS d Return the segment file attributes on the file to the default, i.e. reset to the file access instead of seg- ment access. It not possible to reset a file that has already been segmented. When this option is specified, the attributes are reset to the default. If it is used, it should be the first character in the string. l n Specifies the segment size in units of bytes. The segment_size must be greater than or equal to one mega- byte. This segment size is the size at which the file will be segmented for purposes of archiving and stag- ing. An error is returned if the file is greater than the segment size. s n Specifies the number of segments to stage ahead when staging a segmented file. This means when an offline segment is read, in addition to staging the current segment, the next n segments are also staged. The default n is zero, which means there is no stage read ahead. The maximum n is 255. RETURN VALUES Upon successful completion a value of 0 is returned. Other- wise, a value of -1 is returned and errno is set to indicate the error. ERRORS sam_segment() 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. The file exceeds the speci- fied segment size. EPERM Not the owner or super-user. EFAULT path or ops points to an illegal address. EINTR A signal was caught during the sam_segment() function. ELOOP Too many symbolic links were encountered in translating path. EMULTIHOP Components of path require hopping to multiple remote machines and the file system does not allow it. ENAMETOOLONG The length of the path argument exceeds {PATH_MAX}, or the length of a path com- ponent 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. ENOTSUP License does not support segment. SEE ALSO segment(1) Sun Microsystems Last change: 01 Oct 2004 Introduction to Library Functions sam_stat(3) NAME sam_stat, sam_lstat, sam_segment_stat - Gets file or segment status SYNOPSIS cc [flag ...] file ... -L/opt/SUNWsamfs/lib -R/opt/SUNWsamfs/lib -lsam [library ...] #include "/opt/SUNWsamfs/include/stat.h" int sam_stat(const char *path, struct sam_stat *buf, size_t bufsize); int sam_lstat(const char *path, struct sam_stat *buf, size_t bufsize); int sam_segment_stat(const char *path, struct sam_stat *buf, size_t bufsize); AVAILABILITY SUNWqfs SUNWsamfs DESCRIPTION The sam_stat() function returns file system attributes for the file to which path points. The sam_segment_stat() function works with segmented files. It returns attributes for the file segments to which path points. The sam_lstat() function returns file attributes similar to sam_stat(). The difference is that if file is a symbolic link, sam_lstat() returns information about the link, while sam_stat() returns information about the file or the file's segments that the link references. If these functions succeed, they write file attributes to the structure, or to the array of structures, to which buf points. If they are returning information about a segmented file, they write information about the first file segment to the first structure in the array of structures. They write information about the second file segment to the second structure in the array of structures, etc. Note that when sam_stat() and sam_lstat() are executed on a segmented file, the functions return information about the index inode. The sam_stat and sam_lstat functions are supported in Sun StorEdge QFS, Sun StorEdge SAM-FS, and Sun SAM-QFS environments. The sam_segment_stat function is supported in Sun StorEdge SAM-FS and Sun SAM-QFS environments. OPTIONS These functions accept the following arguments: path Specifies the path to the file. This is the file or segmented file for which the file status is to be obtained. Read, write, or execute permission of the named file is not required, but all directories listed in the path leading to the file must be searchable. buf Specifies a pointer to a structure into which information is placed concerning the file. The functions use one sam_stat structure from this argument for each single file or file segment. The length of buf, in bytes, must be sized as follows: bytes = number_of_segments * sizeof(struct sam_stat) The number_of_segments is 1 for a nonsegmented file (used by sam_stat and sam_lstat). The number_of_segments is greater than 1 for a segmented file (used by sam_segment_stat). For an unsegmented file, buf must be a sam_struct structure. For a segmented file, buf must be an array of sam_struct structures. bufsize Specifies the length of the user's buffer, in bytes, to which buf points. STRUCTURE CONTENTS Table 1 and Table 2 show the content of the structure pointed to by buf. TABLE 1. Members of struct sam_stat That Contain POSIX Standard File Attributes Data Type Field Name Description ulong_t st_mode File mode (see mknod(2) ulong_t st_ino Inode number ulong_t st_dev ID of device containing the file ulong_t st_nlink Number of links ulong_t st_uid Numeric user ID of the file's owner ulong_t st_gid Numeric group ID of the file's owner u_longlong_t st_size File size in bytes time_t st_atime Time of last access time_t st_mtime Time of last data modification time_t st_ctime Time of last file status change The following list describes Table 1's fields in more detail. st_mode The mode of the file as described in mknod(2). In addition to the modes described in mknod(2), the mode of a file may also be S_IFLNK if the file is a symbolic link. Note that S_IFLNK can be returned only by sam_lstat(). st_ino This field uniquely identifies the file in a given file system. The pair st_ino and st_dev uniquely identifies regular files. st_dev This field uniquely identifies the file system that contains the file. st_nlink This field should be used only by administrative commands. st_uid The numeric user ID of the file's owner. st_gid The numeric group ID of the file's owner. st_size For regular files, this is the address of the end of the file. st_atime Time when file data was last accessed. Changed by the following functions: creat, mknod, pipe, utime, and read. st_mtime Time when data was last modified. Changed by the following functions: creat, mknod, pipe, utime, and write. st_ctime Time when file status was last changed. Changed by the following functions: chmod, chown, creat, link, mknod, pipe, unlink, utime, and write. TABLE 2. Members of struct sam_stat That Contain Sun StorEdge QFS, Sun StorEdge SAM-FS, and Sun SAM-QFS File Attributes Data Type Field Name Description uint_t attr File attributes time_t attribute_time Time attributes last changed time_t creation_time Time inode created time_t residence_time Time file changed residence struct sam_copy_s copy[MAX_ARCHIVE] Array of archive copy information uchar_t cs_algo Checksum algorithm indicator uchar_t flags Flags: staging, stage err, etc. uchar_t stripe_width Stripe width set by setfa -s uchar_t stripe_group Stripe group set by setfa -g ulong_t gen Inode generation number ulong_t partial_size Partial size in kilobytes dev_t rdev ID of device if S_IFBLK or S_IFCHR u_longlong_t st_blocks Block count in 512 byte blocks ulong_t segment_size Segment size in megabytes ulong_t segment_number Number of this segment uint_t stage_ahead Number of segment to stage ahead uint_t admin_id admin ID; inherited from directory uint_t allocahead Allocate ahead size set by setfa -A u_longlong_t csum_val[2] 128 checksum value The following list describes Table 2's fields in more detail. attr Attributes assigned to the file by Sun StorEdge QFS, Sun StorEdge SAM-FS, and Sun SAM-QFS functions and operations. attribute_time Time when the Sun StorEdge QFS, Sun StorEdge SAM-FS, and Sun SAM-QFS attributes last changed. Changed by the following functions: sam_archive, sam_release, and sam_stage. Also changed by the automatic archive, release, and stage operations. creation_time Time when the inode was created for the file. residence_time Time when the file changed residency. Changed by the release and stage operations. cs_algo Indicates the algorithm that is used when calculating the data verification value (checksum) for the file. For more information, see ssum(1). flags Flags containing miscellaneous additional information about the file. Includes a bit that indicates that a stage is pending or is in progress on the file. Also includes a bit that indicates that the last attempt to stage the file failed. gen The inode generation number. RETURN VALUES Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and errno is set to indicate the error. ERRORS The sam_stat() and sam_lstat() functions fail if one or more of the following are true: EACCES Search permission is denied for a component of the path prefix. EFAULT Either buf or path points to an illegal address. EINTR A signal was caught during sam_stat() or sam_lstat() function processing. ELOOP Too many symbolic links were encountered in translating path. EMULTIHOP Components of path require hopping to multiple remote machines and the file system does not allow it. ENAMETOOLONG The length of the path argument exceeds {PATH_MAX}, or the length of path 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. EOVERFLOW A component is too large to store in the structure to which buf points. EXAMPLES This example uses sam_segment_stat to obtain the status of a segmented file. struct sam_stat file_info; struct sam_stat *data_seg_info_ptr; int number_of_data_segments; int result; /* * Initialize file_info to be all zero bits: */ memset((void *) &file_info, 0, sizeof(struct sam_stat)); /* * Stat the file using the regular sam_stat function: */ result = sam_stat(path, &file_info, sizeof(struct sam_stat)); if (result != 0) { fprintf(stderr, "Error failed to sam stat the file, %s.\n", path); exit -70; } if (SS_ISSEGMENT_F(file_info.attr)) { /* * File is segmented, how many data segments does it have? */ /* * Determine how many complete (full) segments it has: */ number_of_data_segments = file_info.st_size / (file_info.segment_size * 1048576); /* * Determine if it has one data segment that isn't "full": */ if (file_info.st_size > number_of_data_segments * file_info.segment_size * 1048576) { number_of_data_segments++; } } else { /* * File isn't segmented */ number_of_data_segments = 1; } /* * Allocate enough memory to hold all of the stat information for each * data segment: */ data_seg_info_ptr = (struct sam_stat *) malloc(number_of_data_segments * sizeof(struct sam_stat)); if (data_seg_info_ptr == NULL) { fprintf(stderr, "Error failed to allocate memory for data segment stat operation.\n"); exit -80; } /* * Initialize file_info to be all zero bits: */ memset((void *) data_seg_info_ptr, 0, number_of_data_segments * sizeof(struct sam_stat)); if (SS_ISSEGMENT_F(file_info.attr)) { /* * Use sam_segment_stat to get the stat information for all of the * data segments of the file. */ result = sam_segment_stat(path, data_seg_info_ptr, number_of_data_segments * sizeof(struct sam_stat)); } else { /* * File is not segmented, just use the stat information from the * sam_stat call */ memcpy((void *) data_seg_info_ptr, (void *)file_info, sizeof(struct sam_stat)); } if (!SS_ISSEGMENT_F(file_info.attr)) { number_of_data_segments = 1; data_seg_info_ptr = &file_info_ptr; } /* * data_seg_info_ptr now points to an array of sam_stat structures. * There is one sam_stat structure for each data segment and they are * indexed 0 through number_of_data_segments - 1. * * Do not forget to deallocate the memory buffer pointed to by * data_seg_info_ptr using free. */ SEE ALSO ssum(1). mknod(2), stat(2). Sun Microsystems Last change: 05 Nov 2001 Introduction to Library Functions sam_vsn_stat(3) NAME sam_vsn_stat, sam_segment_vsn_stat - Gets VSN status for an archive copy that overflows VSNs SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsam [ library ... ] #include int sam_vsn_stat(const char *path, int copy, struct sam_section *buf, size_t bufsize); int sam_segment_vsn_stat(const char *path, int copy, int segment_ord, struct sam_section *buf, size_t bufsize); DESCRIPTION The sam_vsn_stat() function obtains information about the VSNs for the archive copy indicated by copy of path, where path points to a non-segmented file. If sam_vsn_stat() is called and path points to a segmented file, then VSN information about the archive copy copy of the segmented file's index inode is returned. The sam_segment_vsn_stat() function obtains information about the VSNs for the archive copy indicated by copy of the data segment indicated by segment_ord of the segmented file pointed to by path. sam_vsn_stat() and sam_segment_vsn_stat() obtain information about the VSNs for the indicated archive copy when the indi- cated archive copy uses multiple VSNs. sam_vsn_stat() and sam_segment_vsn_stat() fail if called to obtain VSN stat information for an archive copy that only uses one VSN. Use the sam_stat() or sam_segment_stat() sub- routines to determine the number of VSNs used by a given archive copy and to get VSN information for archive copies that only use one VSN. sam_vsn_stat() places VSN information for all of the sec- tions that comprise the overflowed archive copy into buf. Read, write, or execute permission of the named file is not required, but all directories listed in the path name lead- ing to the file must be searchable. copy is the archive copy number (0, 1, 2 or 3). segment_ord is the data segment number (0, ..., n_segs - 1) where n_segs is the current number of data segments that comprise the file pointed to by path. buf is a pointer to a sam_section structure into which VSN information is placed concerning the file's archive copy. bufsize is the length of the user's buffer to which buf points. sam_vsn_stat and sam_segment_vsn_stat place VSN information for each overflowed section that comprises the archive copy into buf. Hence, bufsize should be at least sizeof(struct sam_vsn_stat) * n_vsns bytes, where n_vsns is the number of VSNs used by the archived copy. The contents of the structure pointed to by buf include the following struct sam_section members: char vsn[32]; u_longlong_t length; u_longlong_t position; u_longlong_t offset; vsn The VSN of the section. This is a null-terminated string with a maximum of 31 characters. length The length of the section on the volume. position The position of the start of the archive file that contains this section. offset The offset of this file on the archive file. RETURN VALUES Upon successful completion, a value of 0 is returned. Oth- erwise, a value of -1 is returned and errno is set to indi- cate the error. ERRORS sam_vsn_stat() and sam_segment_vsn_stat() fail if one or more of the following are true: EACCES Search permission is denied for a com- ponent of the path prefix. EFAULT buf or path points to an illegal address. EINTR A signal was caught during the sam_vsn_stat() function. ELOOP Too many symbolic links were encountered in translating path. EMULTIHOP Components of path require hopping to multiple remote machines and the file system does not allow it. ENAMETOOLONG The length of the path argument exceeds {PATH_MAX}, or the length of a path com- ponent 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. EOVERFLOW A component is too large to store in the structure pointed to by buf. USAGE sam_vsn_stat Call sam_stat to get the number of VSNs used for the archive copy. The call to sam_stat will write the number of VSNs used by the archive copy in your struct sam_stat buffer in the member copy[copy].n_vsns. If the archive copy uses only one VSN (the number of VSNs is 1), then your pro- gram or script must retrieve the VSN information for the archive copy from the copy member of the sam_stat struc- ture that was filled in when your pro- gram or script called sam_stat. The copy member of the sam_stat structure is of type struct sam_copy_s. sam_segment_vsn_stat Call sam_stat to determine whether the file pointed to by path is segmented. If the file pointed to by path is not segmented, then use sam_vsn_stat to obtain VSN information as detailed above. If the file pointed to by path is seg- mented, then call sam_segment_stat to get the number of VSNs used for the archive copy indicated by copy of the data segment indicated by segment_ord. The call to sam_segment_stat will write the number of VSNs used by the archive copy of the indicated data segment in your array of sam_stat structures in the member located in sam_stat_buff_array[segment_ord].copy[copy].n_vsns. If the archive copy uses only one VSN (the number of VSNs is 1), then your program or script must retrieve the VSN information for the archive copy from the copy member of the element in the array of sam_stat structures that was filled in when your program or script called sam_segment_stat. The copy member of the sam_stat structure is of type struct sam_copy_s and is found in the array of sam_stat struc- tures under the index segment_ord. A struct sam_copy_s structure has the following members: u_longlong_t position; time_t creation_time; uint_t offset; ushort_t flags; short n_vsns; char media[4]; char vsn[32]; position Location of the archive file creation_time Time that the archive copy was created offset Location of the copy in the archive file flags Sun StorEdge SAM-FS and Sun SAM-QFS archive copy status flags. These indicate whether the archive copy has been made, is stale, is damaged, etc. See /opt/SUNWsamfs/include/stat.h for bit masks which can be applied to these flags to resolve the state and status of the archive copy. n_vsns Number of VSNs used by the archived copy. Will be 1 in case of no overflow, will be greater than one if the archive copy over- flows volumes. media Media type. This is a null-terminated string with a maximum of 3 characters. vsn The VSN of the copy. This is a null- terminated string with a maximum of 31 char- acters. If the archive copy uses more than one VSN (the number of VSNs is greater than 1), then your program or script must call sam_vsn_stat or sam_segment_vsn_stat to retrieve the VSN information for all of the sections that comprise the archive copy. Do not call sam_vsn_stat or sam_segment_vsn_stat if the archive copy uses only one VSN (does not overflow). SEE ALSO sam_stat(3) NOTES The Sun StorEdge SAM-FS and the Sun SAM-QFS file systems permit a maximum of MAX_VOLUMES sections per archive copy. Hence, instead of dynamically allocating a buffer of struc- tures, a more efficient method is to to declare a static array with MAX_VOLUMES number of elements. The constant MAX_VOLUMES is declared in the following include file: /opt/SUNWsamfs/include/rminfo.h . Sun Microsystems Last change: 07 Nov 2002 Introduction to Library Functions sam_setfa(3) NAME sam_setfa - Sets attributes on a file or directory SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsam [ library ... ] #include "/opt/SUNWsamfs/include/lib.h" int sam_setfa(const char *path, const char *ops); DESCRIPTION sam_setfa() sets attributes on a file or directory using a SAM-QFS system call. path is the file on which to set the attributes. ops is the character string of options, for example: "ds1". Individual options are described below. OPTIONS A n Specifies the number of bytes to be allocated ahead of a write to the file. The n must be an integer and must be greater than or equal to one kilobyte and less than 4 terabytes. The n is rounded down to units of kilo- bytes. This option is only valid for a regular file. This option should be used when writing large files where more sequential allocation is desired. Note, when the file is closed the blocks are reset to the size of the file. B Specifies the direct I/O attribute be permanently cleared for this file. This means data is transferred indirectly between the user's buffer and disk through the system's page cache. The default I/O mode is buf- fered (uses the page cache). The directio attribute is persistent, remaining until specifically cleared or reset. See directio(3C) for Solaris 2.6 and above for more details. d Return the file attributes on the file to the default, i.e. the stripe is reset to the mount default. When this option is specified, the attributes are reset to the default. If it is used, it should be the first character in the string. D Specifies the direct I/O attribute be permanently set for this file. This means data is transferred directly between the user's buffer and disk. This attribute should only be set for large block aligned sequential I/O. The default I/O mode is buffered (uses the page cache). Direct I/O will not be used if the file is currently memory mapped. The directio attribute is persistent, remaining until specifically cleared or reset. See directio(3C) for Solaris 2.6 and above for more details. g n Specifies the number of the striped group where the file is to be preallocated. n is a number 0 .. 127. n must be a striped_group defined in the file system. l n Specifies the number of bytes to be preallocated to the file. The n must be an integer. This option can only be applied to a regular file. If an I/O event attempts to extend a file preallocated with the L option, the caller receives an ENXIO error. The l option allocates using extent allocation. This means striping is not supported and the file is allocated on 1 disk device or 1 striped group. The L and l options are mutually exclusive. If the file has existing disk blocks, this option is changed to the L option. L n Specifies the number of bytes to be preallocated to the file. The n must be an integer. This option is only valid for a regular file. The L option allocates using standard allocation. This means striping is supported. This also means the file can be extended. The L and l options are mutually exclusive. q Specifies that this file will be linked to the pseudo character device driver, samaio, for the purpose of issuing asynchronous I/O. Note, this option also sets Direct I/O and qwrite. Setting this option may result in greater performance. s n Specifies the number of allocation units to be allo- cated before changing to the next unit. If n is 1, this means the file will stripe across all units with 1 disk allocation unit (DAU) allocated per unit. If n is 0, this means the file will be allocated on one unit until that unit has no space. The default stripe is specified at mount. (see mount_samfs(1M)). Note, EIN- VAL is returned if the user sets stripe > 0 and mismatched stripe groups exist. Mismatched stripe groups means all striped groups do not have the same number of partitions. Striping across mismatched stripe groups is not allowed. RETURN VALUES Upon successful completion a value of 0 is returned. Other- wise, a value of -1 is returned and errno is set to indicate the error. ERRORS sam_setfa() 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_setfa() function. ELOOP Too many symbolic links were encountered in translating path. EMULTIHOP Components of path require hopping to multiple remote machines and the file system does not allow it. ENAMETOOLONG The length of the path argument exceeds {PATH_MAX}, or the length of a path com- ponent 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 setfa(1), ssum(1). mount_samfs(1M). sam_advise(3), sam_ssum(3). directio(3C). Sun Microsystems Last change: 16 Mar 2005 Introduction to Library Functions 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 StorEdge 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 algo- rithm 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 gen- erate 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 com- ponent 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). Sun Microsystems Last change: 05 Nov 2001 Introduction to Library Functions sam_stage(3) NAME sam_stage - Sets stage attributes on a file SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsam [ library ... ] #include "/opt/SUNWsamfs/include/lib.h" int sam_stage(const char *path, const char *ops); DESCRIPTION sam_stage() sets stage attributes on a file or directory using a Sun StorEdge 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: dn. Individual options are described below. OPTIONS a Sets the associative staging attribute on the file or directory. Associative staging is activated when a reg- ular file that has the associative staging attribute set is staged. All files in the same directory that have the associative staging attribute set are staged. If a symbolic link has the associative staging attri- bute set, the file pointed to by the symbolic link is staged. Not valid with stage never attribute -n. d Return the stage attributes on the file to the default, i.e. stage automatically as needed. When this option is specified attributes are reset to the default. If it is used, it should be the first character in the string. i Specifies that the file be staged immediately. n Specifies that the file never be automatically staged. The file will be read directly from the archive media. The mmap function is not supported if the sam_stage n attribute is set. The sam_stage n attribute is not valid with the associative staging attribute a. The sam_stage n attribute is not valid with either of the checksum g (generate) or u (use) attributes. (See ssum(1) or sam_ssum(3)). The stage -n attribute is not supported on Sun SAM-QFS shared file system clients; the entire file is staged when accessed on a client. p Stage the partial blocks back online. s Disable associative staging for the current stage. This is only useful with the i option. This causes only the named file to be staged, not other files in the same directory with the associative attribute set. w Wait for the file to be staged back on-line before com- pleting. Not valid with d or n. 1, 2, 3, 4 Stage in the archive copy specified by the option. RETURN VALUES Upon successful completion a value of 0 is returned. Other- wise, a value of -1 is returned and errno is set to indicate the error. ERRORS sam_stage() fails if one or more of the following are true: EINVAL An invalid option was specified EPERM Not the owner or super-user. ENXIO No archive copy exists, or the specified archive copy does not exist. EFAULT path or ops points to an illegal address. EINTR A signal was caught during the sam_stage() function. ELOOP Too many symbolic links were encountered in translating path. EMULTIHOP Components of path require hopping to multiple remote machines and the file system does not allow it. ENAMETOOLONG The length of the path argument exceeds {PATH_MAX}, or the length of a path com- ponent 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. ENOTSUP License does not support option. NOTE If the application writes (see write(2)) to a file or the application mmaps (see mmap(2)) a file with prot set to PROT_WRITE, the file is staged in and the application waits until the stage has completed. The stage -n attribute is ignored and the file is completely staged back online. SEE ALSO stage(1), ssum(1). sam-stagealld(1M), mount_samfs(1M). mmap(2), write(2). sam_ssum(3). Sun Microsystems Last change: 01 Oct 2004 Introduction to Library Functions sam_stat(3) NAME sam_stat, sam_lstat, sam_segment_stat - Gets file or segment status SYNOPSIS cc [flag ...] file ... -L/opt/SUNWsamfs/lib -R/opt/SUNWsamfs/lib -lsam [library ...] #include "/opt/SUNWsamfs/include/stat.h" int sam_stat(const char *path, struct sam_stat *buf, size_t bufsize); int sam_lstat(const char *path, struct sam_stat *buf, size_t bufsize); int sam_segment_stat(const char *path, struct sam_stat *buf, size_t bufsize); AVAILABILITY SUNWqfs SUNWsamfs DESCRIPTION The sam_stat() function returns file system attributes for the file to which path points. The sam_segment_stat() function works with segmented files. It returns attributes for the file segments to which path points. The sam_lstat() function returns file attributes similar to sam_stat(). The difference is that if file is a symbolic link, sam_lstat() returns information about the link, while sam_stat() returns information about the file or the file's segments that the link references. If these functions succeed, they write file attributes to the structure, or to the array of structures, to which buf points. If they are returning information about a segmented file, they write information about the first file segment to the first structure in the array of structures. They write information about the second file segment to the second structure in the array of structures, etc. Note that when sam_stat() and sam_lstat() are executed on a segmented file, the functions return information about the index inode. The sam_stat and sam_lstat functions are supported in Sun StorEdge QFS, Sun StorEdge SAM-FS, and Sun SAM-QFS environments. The sam_segment_stat function is supported in Sun StorEdge SAM-FS and Sun SAM-QFS environments. OPTIONS These functions accept the following arguments: path Specifies the path to the file. This is the file or segmented file for which the file status is to be obtained. Read, write, or execute permission of the named file is not required, but all directories listed in the path leading to the file must be searchable. buf Specifies a pointer to a structure into which information is placed concerning the file. The functions use one sam_stat structure from this argument for each single file or file segment. The length of buf, in bytes, must be sized as follows: bytes = number_of_segments * sizeof(struct sam_stat) The number_of_segments is 1 for a nonsegmented file (used by sam_stat and sam_lstat). The number_of_segments is greater than 1 for a segmented file (used by sam_segment_stat). For an unsegmented file, buf must be a sam_struct structure. For a segmented file, buf must be an array of sam_struct structures. bufsize Specifies the length of the user's buffer, in bytes, to which buf points. STRUCTURE CONTENTS Table 1 and Table 2 show the content of the structure pointed to by buf. TABLE 1. Members of struct sam_stat That Contain POSIX Standard File Attributes Data Type Field Name Description ulong_t st_mode File mode (see mknod(2) ulong_t st_ino Inode number ulong_t st_dev ID of device containing the file ulong_t st_nlink Number of links ulong_t st_uid Numeric user ID of the file's owner ulong_t st_gid Numeric group ID of the file's owner u_longlong_t st_size File size in bytes time_t st_atime Time of last access time_t st_mtime Time of last data modification time_t st_ctime Time of last file status change The following list describes Table 1's fields in more detail. st_mode The mode of the file as described in mknod(2). In addition to the modes described in mknod(2), the mode of a file may also be S_IFLNK if the file is a symbolic link. Note that S_IFLNK can be returned only by sam_lstat(). st_ino This field uniquely identifies the file in a given file system. The pair st_ino and st_dev uniquely identifies regular files. st_dev This field uniquely identifies the file system that contains the file. st_nlink This field should be used only by administrative commands. st_uid The numeric user ID of the file's owner. st_gid The numeric group ID of the file's owner. st_size For regular files, this is the address of the end of the file. st_atime Time when file data was last accessed. Changed by the following functions: creat, mknod, pipe, utime, and read. st_mtime Time when data was last modified. Changed by the following functions: creat, mknod, pipe, utime, and write. st_ctime Time when file status was last changed. Changed by the following functions: chmod, chown, creat, link, mknod, pipe, unlink, utime, and write. TABLE 2. Members of struct sam_stat That Contain Sun StorEdge QFS, Sun StorEdge SAM-FS, and Sun SAM-QFS File Attributes Data Type Field Name Description uint_t attr File attributes time_t attribute_time Time attributes last changed time_t creation_time Time inode created time_t residence_time Time file changed residence struct sam_copy_s copy[MAX_ARCHIVE] Array of archive copy information uchar_t cs_algo Checksum algorithm indicator uchar_t flags Flags: staging, stage err, etc. uchar_t stripe_width Stripe width set by setfa -s uchar_t stripe_group Stripe group set by setfa -g ulong_t gen Inode generation number ulong_t partial_size Partial size in kilobytes dev_t rdev ID of device if S_IFBLK or S_IFCHR u_longlong_t st_blocks Block count in 512 byte blocks ulong_t segment_size Segment size in megabytes ulong_t segment_number Number of this segment uint_t stage_ahead Number of segment to stage ahead uint_t admin_id admin ID; inherited from directory uint_t allocahead Allocate ahead size set by setfa -A u_longlong_t csum_val[2] 128 checksum value The following list describes Table 2's fields in more detail. attr Attributes assigned to the file by Sun StorEdge QFS, Sun StorEdge SAM-FS, and Sun SAM-QFS functions and operations. attribute_time Time when the Sun StorEdge QFS, Sun StorEdge SAM-FS, and Sun SAM-QFS attributes last changed. Changed by the following functions: sam_archive, sam_release, and sam_stage. Also changed by the automatic archive, release, and stage operations. creation_time Time when the inode was created for the file. residence_time Time when the file changed residency. Changed by the release and stage operations. cs_algo Indicates the algorithm that is used when calculating the data verification value (checksum) for the file. For more information, see ssum(1). flags Flags containing miscellaneous additional information about the file. Includes a bit that indicates that a stage is pending or is in progress on the file. Also includes a bit that indicates that the last attempt to stage the file failed. gen The inode generation number. RETURN VALUES Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and errno is set to indicate the error. ERRORS The sam_stat() and sam_lstat() functions fail if one or more of the following are true: EACCES Search permission is denied for a component of the path prefix. EFAULT Either buf or path points to an illegal address. EINTR A signal was caught during sam_stat() or sam_lstat() function processing. ELOOP Too many symbolic links were encountered in translating path. EMULTIHOP Components of path require hopping to multiple remote machines and the file system does not allow it. ENAMETOOLONG The length of the path argument exceeds {PATH_MAX}, or the length of path 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. EOVERFLOW A component is too large to store in the structure to which buf points. EXAMPLES This example uses sam_segment_stat to obtain the status of a segmented file. struct sam_stat file_info; struct sam_stat *data_seg_info_ptr; int number_of_data_segments; int result; /* * Initialize file_info to be all zero bits: */ memset((void *) &file_info, 0, sizeof(struct sam_stat)); /* * Stat the file using the regular sam_stat function: */ result = sam_stat(path, &file_info, sizeof(struct sam_stat)); if (result != 0) { fprintf(stderr, "Error failed to sam stat the file, %s.\n", path); exit -70; } if (SS_ISSEGMENT_F(file_info.attr)) { /* * File is segmented, how many data segments does it have? */ /* * Determine how many complete (full) segments it has: */ number_of_data_segments = file_info.st_size / (file_info.segment_size * 1048576); /* * Determine if it has one data segment that isn't "full": */ if (file_info.st_size > number_of_data_segments * file_info.segment_size * 1048576) { number_of_data_segments++; } } else { /* * File isn't segmented */ number_of_data_segments = 1; } /* * Allocate enough memory to hold all of the stat information for each * data segment: */ data_seg_info_ptr = (struct sam_stat *) malloc(number_of_data_segments * sizeof(struct sam_stat)); if (data_seg_info_ptr == NULL) { fprintf(stderr, "Error failed to allocate memory for data segment stat operation.\n"); exit -80; } /* * Initialize file_info to be all zero bits: */ memset((void *) data_seg_info_ptr, 0, number_of_data_segments * sizeof(struct sam_stat)); if (SS_ISSEGMENT_F(file_info.attr)) { /* * Use sam_segment_stat to get the stat information for all of the * data segments of the file. */ result = sam_segment_stat(path, data_seg_info_ptr, number_of_data_segments * sizeof(struct sam_stat)); } else { /* * File is not segmented, just use the stat information from the * sam_stat call */ memcpy((void *) data_seg_info_ptr, (void *)file_info, sizeof(struct sam_stat)); } if (!SS_ISSEGMENT_F(file_info.attr)) { number_of_data_segments = 1; data_seg_info_ptr = &file_info_ptr; } /* * data_seg_info_ptr now points to an array of sam_stat structures. * There is one sam_stat structure for each data segment and they are * indexed 0 through number_of_data_segments - 1. * * Do not forget to deallocate the memory buffer pointed to by * data_seg_info_ptr using free. */ SEE ALSO ssum(1). mknod(2), stat(2). Sun Microsystems Last change: 05 Nov 2001 Introduction to Library Functions sam_unarchive(3) NAME sam_unarchive - Removes archive copies for a file or direc- tory SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsam [ library ... ] #include "/opt/SUNWsamfs/include/lib.h" int sam_unarchive(const char *path, int num_opts, ... ); DESCRIPTION sam_unarchive() lets you remove an archive copy of a file or a directory using a Sun StorageTek SAM-FS or Sun SAM-QFS system call. path is the file of which to delete archive entries, followed by a sequence of num_opts input characters or options. Individual options are described below. For example, if you have used the sam_archive(3) function to request that a file be archived, you can use the sam_unarchive(3) function to delete that archive copy. The specifications for the archive copy (c copy_no) and/or the media type and VSN (m media_type [v vsn]) determine which archive copy is deleted. There are several ways to specify one or more archive entries to be unarchived. These ways are as follows: o By copy number o By copy number, media type, and VSN o By copy number and media type o By media type o By media type and VSN OPTIONS c copy_no Deletes the specified archive copy_no. Specify 1, 2, 3, or 4 for copy_no. If one or more 'c' options are are specified, only those archive copies (1, 2, 3, or 4) are deleted. Either a "c copy_no" or a "m media" option must be specified. M Unarchives metadata only. This includes directories, the segment index, and removable media files. Regular files and symbolic links are not unarchived. If you are unarchiving a directory, you must specify the "M" option. m media Deletes all archive copies on the specified media_type. For the list of possible media_type specifications, see the mcf(4) man page. Either a "c copy_no" or a "m media" option must be specified. If you specify a "m media" option, you can also specify a "v vsn" option. o Specifies that the file must be online before its archive entry is deleted. If the file is offline, the sam_unarchive function stages the file to disk before deleting any entries. v vsn Deletes the archive copies on vsn. For vsn, specify a volume serial name (VSN). If you specify a "v vsn" option, you must also specify a "m media" option. RETURN VALUES Upon successful completion a value of 0 is returned. Other- wise, a value of -1 is returned and errno is set to indicate the error. ERRORS sam_unarchive() 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 Argument points to an illegal address. EINTR A signal was caught during the sam_unarchive() 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 com- ponent 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. NOTE If the last (undamaged) copy of a file would be unarchived, sam_unarchive would not unarchive that copy. SEE ALSO unarchive(1m), archive(1m), sam_archive(3), mcf(4) Sun Microsystems Last change: 15 May 2007 Introduction to Library Functions sam_undamage(3) NAME sam_undamage - Clears damaged and stale status of archive entries of a file or directory SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsam [ library ... ] #include "/opt/SUNWsamfs/include/lib.h" int sam_undamage(const char *path, int num_opts, ... ); DESCRIPTION Using a Sun StorageTek SAM-FS or Sun SAM-QFS system call, sam_undamage() lets you mark archive copies of a file or a directory as undamaged and not stale, based on the archive copy number and/or the media type and VSN specified. The function also marks the file itself as undamaged. path is the file on which to clear the attributes, followed by a sequence of num_opts input characters or options. Indivi- dual options are described below. There are several ways to mark one or more copies as undam- aged and unstale. These ways are as follows: o By copy number o By copy number, media type, and VSN o By copy number and media type o By media type o By media type and VSN OPTIONS a Rearchives the damaged copy. c copy_no Marks the specified archive copy number as undam- aged. If one or more 'c' options are specified, only those archive copies (1, 2, 3, or 4) are marked as undamaged. Specify 1, 2, 3, or 4 for copy_no. Either a "c copy_no" or a "m media" option must be specified. M Marks only metadata as undamaged. This includes directories, the segment index and removable-media files. Regular files are not marked as undamaged. If you are marking a directory as undamaged, you must specify the "M" option. m media_type Marks all copies from the specified media_type as undamaged. For the list of possible media_type specifications, see the mcf(4) man page. Either a "c copy_no" or a "m media" option must be speci- fied. If you specify a "m media" option, you can also specify a "v vsn" option. v vsn Marks the archive copies on vsn as undamaged. For vsn, specify a volume serial name (VSN). If you specify a "v vsn" option, you must also specify a "m media" option. RETURN VALUES Upon successful completion a value of 0 is returned. Other- wise, a value of -1 is returned and errno is set to indicate the error. ERRORS sam_undamage() 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 Argument points to an illegal address. EINTR A signal was caught during the sam_undamage() 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 com- ponent 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 damage(1m), undamage(1m), sam_damage(3), mcf(4) Sun Microsystems Last change: 15 May 2007 Introduction to Library Functions sam_unrearch(3) NAME sam_unrearch - Removes rearchive attributes on a file or directory SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsam [ library ... ] #include "/opt/SUNWsamfs/include/lib.h" int sam_unrearch(const char *path, int num_opts, ... ); DESCRIPTION sam_unrearch() lets you remove a request to rearchive a file or a directory using a Sun StorageTek SAM-FS or Sun SAM-QFS system call. path is the file on which to remove the attri- butes, followed by a sequence of num_opts input characters or options. Individual options are described below. For example, if you have used the sam_rearch(3) function to request that a file be rearchived, you can use the sam_unrearch function to clear the bit that the sam_rearch(3) function had set. The specifications for the archive copy (c copy_no) and/or the media type and VSN (m media_type [v vsn]) determine which archive copy is affected. There are several ways to remove the request to rearchive from one or more archive entries. These ways are as fol- lows: o By copy number o By copy number, media type, and VSN o By copy number and media type o By media type o By media type and VSN OPTIONS c copy_no Removes the rearchive request for copy_no. Specify 1, 2, 3, or 4 for copy_no. If one or more 'c' options are are specified, the function removes the rearchive request from only those archive copies (1, 2, 3, or 4). Either a "c copy_no" or a "m media" option must be specified. M Removes rearchive requests for metadata only. This includes directories, the segment index, and removable media files. Regular files and symbolic links are not unrearchived. If you are unarchiving a directory, you must specify the "M" option. m media Removes rearchive requests from all archive copies on the specified media_type. For the list of possible media_type specifications, see the mcf(4) man page. Either a "c copy_no" or a "m media" option must be specified. If you specify a "m media" option, you can also specify a "v vsn" option. v vsn Removes the rearchive requests for the archive copies on vsn. For vsn, specify a volume serial name (VSN). If you specify a "v vsn" option, you must also specify a "m media" option. RETURN VALUES Upon successful completion a value of 0 is returned. Other- wise, a value of -1 is returned and errno is set to indicate the error. ERRORS sam_unrearch() 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 Argument points to an illegal address. EINTR A signal was caught during the sam_unrearch() 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 com- ponent 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 unrearch(1m), rearch(1m), sam_rearch(3), mcf(4) Sun Microsystems Last change: 15 May 2007 Introduction to Library Functions sam_vsn_stat(3) NAME sam_vsn_stat, sam_segment_vsn_stat - Gets VSN status for an archive copy that overflows VSNs SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsam [ library ... ] #include int sam_vsn_stat(const char *path, int copy, struct sam_section *buf, size_t bufsize); int sam_segment_vsn_stat(const char *path, int copy, int segment_ord, struct sam_section *buf, size_t bufsize); DESCRIPTION The sam_vsn_stat() function obtains information about the VSNs for the archive copy indicated by copy of path, where path points to a non-segmented file. If sam_vsn_stat() is called and path points to a segmented file, then VSN information about the archive copy copy of the segmented file's index inode is returned. The sam_segment_vsn_stat() function obtains information about the VSNs for the archive copy indicated by copy of the data segment indicated by segment_ord of the segmented file pointed to by path. sam_vsn_stat() and sam_segment_vsn_stat() obtain information about the VSNs for the indicated archive copy when the indi- cated archive copy uses multiple VSNs. sam_vsn_stat() and sam_segment_vsn_stat() fail if called to obtain VSN stat information for an archive copy that only uses one VSN. Use the sam_stat() or sam_segment_stat() sub- routines to determine the number of VSNs used by a given archive copy and to get VSN information for archive copies that only use one VSN. sam_vsn_stat() places VSN information for all of the sec- tions that comprise the overflowed archive copy into buf. Read, write, or execute permission of the named file is not required, but all directories listed in the path name lead- ing to the file must be searchable. copy is the archive copy number (0, 1, 2 or 3). segment_ord is the data segment number (0, ..., n_segs - 1) where n_segs is the current number of data segments that comprise the file pointed to by path. buf is a pointer to a sam_section structure into which VSN information is placed concerning the file's archive copy. bufsize is the length of the user's buffer to which buf points. sam_vsn_stat and sam_segment_vsn_stat place VSN information for each overflowed section that comprises the archive copy into buf. Hence, bufsize should be at least sizeof(struct sam_vsn_stat) * n_vsns bytes, where n_vsns is the number of VSNs used by the archived copy. The contents of the structure pointed to by buf include the following struct sam_section members: char vsn[32]; u_longlong_t length; u_longlong_t position; u_longlong_t offset; vsn The VSN of the section. This is a null-terminated string with a maximum of 31 characters. length The length of the section on the volume. position The position of the start of the archive file that contains this section. offset The offset of this file on the archive file. RETURN VALUES Upon successful completion, a value of 0 is returned. Oth- erwise, a value of -1 is returned and errno is set to indi- cate the error. ERRORS sam_vsn_stat() and sam_segment_vsn_stat() fail if one or more of the following are true: EACCES Search permission is denied for a com- ponent of the path prefix. EFAULT buf or path points to an illegal address. EINTR A signal was caught during the sam_vsn_stat() function. ELOOP Too many symbolic links were encountered in translating path. EMULTIHOP Components of path require hopping to multiple remote machines and the file system does not allow it. ENAMETOOLONG The length of the path argument exceeds {PATH_MAX}, or the length of a path com- ponent 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. EOVERFLOW A component is too large to store in the structure pointed to by buf. USAGE sam_vsn_stat Call sam_stat to get the number of VSNs used for the archive copy. The call to sam_stat will write the number of VSNs used by the archive copy in your struct sam_stat buffer in the member copy[copy].n_vsns. If the archive copy uses only one VSN (the number of VSNs is 1), then your pro- gram or script must retrieve the VSN information for the archive copy from the copy member of the sam_stat struc- ture that was filled in when your pro- gram or script called sam_stat. The copy member of the sam_stat structure is of type struct sam_copy_s. sam_segment_vsn_stat Call sam_stat to determine whether the file pointed to by path is segmented. If the file pointed to by path is not segmented, then use sam_vsn_stat to obtain VSN information as detailed above. If the file pointed to by path is seg- mented, then call sam_segment_stat to get the number of VSNs used for the archive copy indicated by copy of the data segment indicated by segment_ord. The call to sam_segment_stat will write the number of VSNs used by the archive copy of the indicated data segment in your array of sam_stat structures in the member located in sam_stat_buff_array[segment_ord].copy[copy].n_vsns. If the archive copy uses only one VSN (the number of VSNs is 1), then your program or script must retrieve the VSN information for the archive copy from the copy member of the element in the array of sam_stat structures that was filled in when your program or script called sam_segment_stat. The copy member of the sam_stat structure is of type struct sam_copy_s and is found in the array of sam_stat struc- tures under the index segment_ord. A struct sam_copy_s structure has the following members: u_longlong_t position; time_t creation_time; uint_t offset; ushort_t flags; short n_vsns; char media[4]; char vsn[32]; position Location of the archive file creation_time Time that the archive copy was created offset Location of the copy in the archive file flags Sun StorEdge SAM-FS and Sun SAM-QFS archive copy status flags. These indicate whether the archive copy has been made, is stale, is damaged, etc. See /opt/SUNWsamfs/include/stat.h for bit masks which can be applied to these flags to resolve the state and status of the archive copy. n_vsns Number of VSNs used by the archived copy. Will be 1 in case of no overflow, will be greater than one if the archive copy over- flows volumes. media Media type. This is a null-terminated string with a maximum of 3 characters. vsn The VSN of the copy. This is a null- terminated string with a maximum of 31 char- acters. If the archive copy uses more than one VSN (the number of VSNs is greater than 1), then your program or script must call sam_vsn_stat or sam_segment_vsn_stat to retrieve the VSN information for all of the sections that comprise the archive copy. Do not call sam_vsn_stat or sam_segment_vsn_stat if the archive copy uses only one VSN (does not overflow). SEE ALSO sam_stat(3) NOTES The Sun StorEdge SAM-FS and the Sun SAM-QFS file systems permit a maximum of MAX_VOLUMES sections per archive copy. Hence, instead of dynamically allocating a buffer of struc- tures, a more efficient method is to to declare a static array with MAX_VOLUMES number of elements. The constant MAX_VOLUMES is declared in the following include file: /opt/SUNWsamfs/include/rminfo.h . Sun Microsystems Last change: 07 Nov 2002 Introduction to Library Functions usam_mig_cancel_stage_req(3) NAME usam_mig_cancel_stage_req - Cancels a foreign media stage request SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsamut [ library ... ] #include "/opt/SUNWsamfs/include/mig.h" int usam_mig_cancel_stage_req(tp_stage_t *stage_req ); AVAILABILITY SUNWsamfs DESCRIPTION usam_mig_cancel_stage_req() cancels a stage request from the foreign data migration program, written by the integrator. The stager daemon, sam-stagerd, is expected to cancel the stage request on its worklist. Only the inode and fseq can be used to find the stage request to be canceled. stage_req is a pointer to a tp_api structure into which information is placed regarding the offset, size, position, etc. of the data file. The contents of the structure pointed to by stage_req include the following members: offset_t offset; /* Offset from beginning of the file */ offset_t size; /* Size of the file to stage */ long long position; /* The position field from the archive info in the inode */ ino_t inode; /* Inode number from the file system */ vsn_t space; /* VSN field from the archive information in the inode */ equ_t fseq; /* Equipment number of family set in the inode */ char media_type[2]; /* 2 character media type for the foreign media*/ offset The offset from the beginning of the file for this stage request. As the system is reading a "stage never" file, the file offset moves down the file. For a normal stage of a file the stage offset is zero. size The size of the file to stage for this stage request. During a "stage never" request, this is the size the file system wants to deliver at this time. For a normal stage of a file the size is the size of the file. position The position field(s) from the archive information in the inode. inode The inode number from the file system. vsn The vsn field from the archive information in the inodes. fseq The equipment number of the family set for the inode. media_type[2] The two character media type for the foreign media. Upon succesful initialization a value of 0 is returned. Otherwise, a value of 1 is returned and errno is set to indicate the error. ERRORS usam_mig_cancel_stage_req() fails if the following is true: ECANCELED FILES /opt/SUNWsamfs/migkit/mig_cd.c The example Migration Toolkit program. /etc/opt/SUNWsamfs/mcf The configuration file for Sun StorEdge SAM-FS and Sun SAM-QFS file systems. SEE ALSO mcf(4). Sun Microsystems Last change: 05 Nov 2001 Introduction to Library Functions usam_mig_initialize(3) NAME usam_mig_initialize - Initializes the migration interface SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsamut [ library ... ] #include "/opt/SUNWsamfs/include/mig.h" int usam_mig_initialize(int stage_count); AVAILABILITY SUNWsamfs DESCRIPTION usam_mig_initialize() is the initialization routine for the Sun StorEdge SAM-FS Migration Toolkit. It is called by the foreign media "device" to allow the interface to initialize any local structs, threads, etc. stage_count is the maximum number of stage requests that may be outstanding at one time. Every stage request for a foreign media type is handed to the stager daemon. sam-stagerd(1M) must be able to handle this stage_count requests at one time. RETURN VALUES Upon succesful initialization a value of 0 is returned. Otherwise, a value of 1 is returned and errno is set to indicate the error. FILES /opt/SUNWsamfs/migkit/mig_cd.c The example Migration Toolkit program. /etc/opt/SUNWsamfs/mcf The configuration file for Sun StorEdge SAM-FS and Sun SAM-QFS file systems. SEE ALSO sam-stagerd(1M). mcf(4). Sun Microsystems Last change: 05 Nov 2001 Introduction to Library Functions usam_mig_stage_file_req(3) NAME usam_mig_stage_file_req - Stages request from the foreign data migration program SYNOPSIS cc [ flag ... ] file ... -L/opt/SUNWsamfs/lib -lsamut [ library ... ] #include "/opt/SUNWsamfs/include/mig.h" int usam_mig_stage_file_req(); AVAILABILITY SUNWsamfs DESCRIPTION usam_mig_stage_file_req() is the stage request routine for the Sun StorEdge SAM-FS Migration Toolkit. The foreign data migration program adds this stage request to an internally- generated worklist being maintained by third party API. This worklist should be processed by a thread started by usam_mig_initialize(). This worklist is processed by a pro- gram started with usam_mig_initialize(). The thread finds and positions the media to stage the file through stage_api. RETURN VALUES A successful stage request returns a value of 0. Otherwise, a value of 1 is returned and errno is passed to the file system. ERRORS usam_mig_stage_file_req() fails if the following is true: EEXIST This is a duplicate stage request for a file. FILES /opt/SUNWsamfs/migkit/mig_cd.c The example Migration Toolkit program. /etc/opt/SUNWsamfs/mcf The configuration file for Sun StorEdge SAM-FS and Sun SAM-QFS file systems. SEE ALSO sam_migd(3). mcf(4). Sun Microsystems Last change: 05 Nov 2001