samgetmap(1M)

NAME
     samgetmap - Obtains disk file storage information

SYNOPSIS
     /opt/SUNWsamfs/tools/samgetmap [-a allocsize] [-c] [-f] [-h]
     [-l setlen] [-m minalloc] [-n nbytes] [-s startaddr] [-u]
     [-w] [-M] [-U] [-V] file

AVAILABILITY
     Oracle Corporation Internal

DESCRIPTION
     The samgetmap command provides a test interface to the
     SANergy File Map API routines.  The samgetmap command must
     be run as root.

OPTIONS
     This command accepts the following options:

     -a allocsize
               Requests allocation of allocsize bytes of storage
               to file through the FS_SetFileSizes request.  The
               allocsize must be an integer in the following
               range:

               0 < allocsize < 2**31

               For more information, see the OPERATIONS section
               of this man page.

     -c        Requests a canonical map.  FS_M_FLAG_CANONICAL is
               set for the FS_GetLockedMap request.  For more
               information, see the OPERATIONS section of this
               man page.

     -f        Requests a non-sparse allocation map.
               FS_M_FLAG_NO_HOLE is set for the FS_GetLockedMap
               request.  For more information, see the OPERATIONS
               section of this man page.

     -h        Causes samgetmap to write a short usage message to
               stdout.

     -l setlen Sets the file length to setlen bytes.

     -m minalloc
               Uses FS_SetFileSizes to request the allocation of
               minalloc bytes of storage for file.  minalloc must
               be an integer in the following range:

               -1 < minalloc < allocsize

               If minalloc is within this range and the
               allocation request partially succeeds, such that
               minalloc or more bytes are allocated but fewer
               than allocsize bytes are allocated, a unique error
               code is returned to indicate partial success.  For
               more information, see the OPERATIONS section of
               this man page.

               samgetmap's behavior is undefined if minalloc is
               less than -1 or greater than allocsize.  For more
               information on allocsize, see the -a option.

     -n nbytes Specifies that the allocation map returned by the
               FS_GetLockedMap call return information about the
               location of at least nbytes of data.  For more
               information, see the OPERATIONS section of this
               man page.

     -s startaddr
               Requests that the allocation map returned by the
               FS_GetLockedMap request return the information
               about file's storage beginning at byte startaddr
               in the file.  For more information, see the
               OPERATIONS section of this man page.

     -u        Sets FS_M_FLAG_UNLOCKED in the call to
               FS_GetLockedMap.  file is not locked by the
               FS_GetLockedMap call.  For more information, see
               the OPERATIONS section of this man page.

     -w        Sets FS_M_FLAG_WAIT for the call to
               FS_GetLockedMap.  If the file is online, this
               option has no effect.  If the file is offline, the
               file is staged in before the file's map is
               returned.  For more information, see the
               OPERATIONS section of this man page.

     -M        Prevents the call to FS_GetLockedMap from being
               made.  For more information, see the OPERATIONS
               section of this man page.

     -U        Prevents the call to FS_UnlockMap from being made,
               leaving the file locked (unless the -u option is
               also specified).  For more information, see the
               OPERATIONS section of this man page.

               NOTE:  Use of this option makes it impossible to
               unmount the file system that file resides in until
               the file is somehow unlocked (see also
               samunhold(1M) to remove all file locks (holds) on
               a file system).  Specifying the -u and -U options
               together on the command line insures that the file
               is unlocked upon exit from samgetmap.

     -V        Report the value returned by the FS_GetVersion(),
               added to the SANergy 2.2 API, which indicates the
               library revision value.  Present valid values are
               220 (for SANergy 2.2), and 230 (for SANergy
               2.3/3.1).

     file      Specifies the file for which disk storage
               information is requested.

     The samgetmap command should not be executed if SANergy File
     Sharing is running on the file system.  Specifically, the
     administrator should ensure that the following conditions
     are true:

     o There are no SANergy applications running on any client,
       possibly including the server itself.

     o The file system in question is not fused on any SANergy
       clients.

OPERATIONS
     The samgetmap program operates as follows:

     1. The program calls the AFS_GetCookies routine to obtain
        two cookies, one for the file system that file resides on
        (a volume cookie) and the other for file itself (a file
        cookie).

     2. The program calls FS_GetLockedMap, using the cookies
        obtained by FS_GetCookies.  This call is not made if the
        -M option is present.  The parameters to this call can be
        specified or modified by the command line options -s, -n,
        -c, -f, -u, and -w.

     3. The program calls FS_SetFileSizes.  The parameters to
        this call can be specified or modified by the command
        line options -a, -l, and -m.

     4. The program calls FS_UnlockMap.  This call is not made if
        the -U option is present on the command line.

     The result of each call is written in a message to stdout.

EXAMPLES
     The following example shows how to use samgetmap:

     ceres# samgetmap /qfs1/foo
     AFS_GetCookies("/qfs1/foo", &vc, &fc) = 0 (FS_E_SUCCESS (OK))

     Volcookie:

               0  0  0 20 73 56 6d 43          0  b  0  0 3a 94 44 4d
               0  1  5  6  0  0  0  0          0  0  3  0  2 ed a0  0

     Filecookie:
               0  0  0 10 73 46 6d 43          0  0  0  7  0  0  0  1
               0  0  0  0  0  0  0  0          0  0  0  0  0  0  0  0

     FS_GetLockedMap(&vc, &fc, 0, -1, 0, ffbaf448, ffbaf340)  = 0 (FS_E_SUCCESS
     (OK))
     returned buflen = 88
     msgLen       = 88
     vendorStatus = 0
     fileSize     = 16384000
     allocation   = 16416768
     nExtents     = 1
     extentType   = 2        (SIMPLE)

     sExtent[0]
             volumeOrdinal = 1
             blockOffset   = 20
             nBlocks = 7d40

     FS_SetFileSizes(&vc, &fc, 0, ffffffffffffffff, ffffffffffffffff, ffffffffff
     ffffff)  = 0 (FS_E_SUCCESS (OK))
     FS_UnlockMap(&vc, &fc) = 0 (FS_E_SUCCESS (OK))

NOTES
     The samgetmap command typically issues holds (locks) to
     file.  This can interfere with the operation of SANergy File
     Sharing, possibly causing file system corruption.

SEE ALSO
     samgetvol(1M), samunhold(1M).