FFPOS(3C) Last changed: 2-17-98
NAMEffpos - Positions files opened using flexible file I/O
SYNOPSIS
#include <ffio.h>
UNICOS and UNICOS/mk systems:
int ffpos (int fd, int cmd, long *arg , int len, struct ffsw
*stat);
IRIX systems:
off_t ffpos (int fd, int cmd, void *arg , int len, struct ffsw
*stat);
IMPLEMENTATION
UNICOS, UNICOS/mk, and IRIX systems
DESCRIPTION
The ffpos function provides a way of positioning files opened by
ffopen or ffopens (see ffopen(3C)), using flexible file I/O (FFIO).
The arguments are as follows:
fd Value returned by ffopen or ffopens.
cmd Specifies a value defined in header file ffio.h. See the
following subsection, VALUES FOR cmd ARGUMENT.
arg The type and value of this argument is cmd specific. See
preceding descriptions.
len If cmd = FP_GETPOS or FP_SETPOS, len specifies the number of
Cray words in arg. This parameter is ignored for other values
of cmd.
stat Pointer to the status return structure.
Values for cmd Argument
The following values can be used for the cmd argument introduced
above.
FP_BSEEK
Sets the current file position as specified by *arg and *(arg+1).
Not supported on IRIX systems. *arg contains the bit position
requested; this must be a byte boundary. *(arg+1) specifies one
of the following values, defined in header file stdio.h:
0 or SEEK_SET
Sets the pointer to the value of *arg, which must be a
non-negative integer.
1 or SEEK_CUR
Sets the pointer to the current position, plus or minus *arg.
This is supported only in the following layers that are not
record-oriented; these layers are specified to assign -F as
follows: syscall, sds, mr (memory resident), cache, cachea,
bufa, er90.
2 or SEEK_END
Sets the pointer to the end of the file, minus *arg. *arg
must be a non-negative integer. Not all layers support this
option.
FP_GABS
Returns information about the current position in arg, which can
later be used by a call to ffpos with cmd = FP_SABS. arg is a
pointer to structure fp_abs (defined in header file ffio.h).
This call is useful only for online tape and ER90 files. It may
be used with the tape, er90, or bufa layers on UNICOS systems. It
may be used with the tape layer on CRAY T3E systems. ER90 files
are not supported on CRAY T3E systems. For some devices, some of
the fields in fp_abs may be unused. When this request is made
after a write function, the library and tape driver flush all
remaining data from the write behind to the tape before attempting
to get the position. When this request is made after a read
request, an approximate address is returned, since there may be
data buffered in the controller, system buffers, or library
buffers. FP_GABS does not return information about the volume
serial number (VSN) currently in use.
FP_GETPOS
Returns information about the current position in arg, which can
later be used by a call to ffpos with cmd 0=FP_SETPOS. For online
tape files, 2 Cray words are returned in arg. For files assigned
with assign -F er90, 4 Cray words are returned in arg. For files
assigned with -F cos,er90, 6 Cray words are returned in arg. For
all other file types, 1 Cray word is returned in arg. For ER90
files, the information returned does not include the VSN. When
using the information returned in a call to ffpos with
cmd=FP_SETPOS, you must ensure that you are positioned on the
correct volume. This command is unsupported for ER90 files that
use the FFIO tape layer. Available on UNICOS and UNICOS/mk
systems. ER90 files and the er90 layer are not supported on
CRAY T3E systems.
FP_SABS
Sets the position as specified in arg. The information in arg
should have been obtained by a previous call to ffpos with
cmd = FP_GABS. arg is a pointer to structure fp_abs. This call
is useful only for online tape and ER90 files. FP_SABS assumes
that you are currently positioned on the correct VSN. You must
have permission to set the position to the specified address when
using absolute track address positioning. Tape manager permission
is required for IBM-compatible tapes. For ER90 files, tape
manager permission is required to position outside the current
partition. Bypass-label permission or tape manager permission is
required to position outside the current file, or past a user tape
mark. Available on UNICOS and UNICOS/mk systems. ER90 files and
the er90 layer are not supported on CRAY T3E systems.
FP_SETPOS
Sets the position as specified by the information in arg. The
information in arg should have been obtained by a previous call to
ffpos with cmd = FP_GETPOS.
Not available on IRIX systems.
FP_SKIPF
This value is valid only for online tape files on UNICOS systems
and on CRAY T3E systems and for ER90 files on UNICOS systems. It
directs the system to skip a specified number of files from the
current position. The file will not be positioned beyond BOD or
EOD. This is used for positioning by user tapemark (see the -T
option on the tpmnt(1) command). It may not be used to position
to different files within a multifile volume (see the -q option of
the tpmnt(1) command. arg is a pointer to structure ffp_skipf_s
(also defined in header file ffio.h). This cmd is valid with the
following FFIO layers: tape. The fields of this structure have
the following meaning:
ffp_nfil On input, specifies the number of files to skip. If
the value is negative, the file is positioned
backward. On output, contains the number of files
skipped.
ffp_nrec Currently unused.
FP_SKIPTPMK
This value is valid only for online tape files on UNICOS systems
and on CRAY T3E systems. It directs the system to skip a
specified number of tape marks from the current position. The file
will not be positioned beyond BOD or EOD. This is used for
positioning by user tapemark (see the -T option on the tpmnt(1)
command). arg is a pointer to structure ffp_skiptpmk_s (defined
in <ffio.h>). The fields in this structure have the following
meaning:
ffp_ntpmk On input, specifies the number of tape marks to skip.
If the value is negative, the file is positioned
backwards. On output, this field contains the number
of tape marks left to position.
unused1 This field is reserved.
The FP_SKIPTPMK cmd functions differently from FP_SKIPF. Except
in the case where you request positioning past EOD, FP_SKIPF will
position you at the beginning of a file; that is, FP_SKIPF will
position you either at BOD, immediately after a user tape mark, or
at EOD. FP_SKIPTPMK functions like the ioctl TR_PTMS described in
the Tape Subsystem User's Guide, publication SG-2051. It skips
the specified number of tape marks. If skipping forward, it will
position you directly after a user tape mark or at EOD. If
skipping backwards, it will position you directly before a user
tape mark or at BOD. This cmd is valid with the following FFIO
layers: tape.
FP_SETTP
arg is a pointer to structure ffp_settp_s (also defined in header
file ffio.h). This cmd is valid with the following FFIO layers:
tape.
The er90 layer is not supported on CRAY T3E systems.
On input, the fields of ffp_settp_s have the following meaning:
ffp_nb
Number of blocks to position; should always be a positive
number.
ffp_nbs_p
Indicates the direction of block positioning. The following
values are defined in header <ffio.h>:
FP_TPOS_BACK
Indicates that the ffp_nb field is the number of blocks to
skip backward, relative to the current position.
FP_TPOS_FORW
Indicates that the ffp_nb field is the number of blocks to
skip forward, relative to the current position.
FP_TPOS_ABS
Indicates that the ffp_nb field is an absolute block
number, relative to the last tape mark number or beginning
of the volume. If a nonzero value is specified for the
ffp_nv field, positioning is absolute with respect to that
tape volume. If ffp_nv is 0, and the -T option was not
present on the tpmnt(1) command, the position is absolute
with respect to the current tape volume. If ffp_nv is 0,
and the -T option was present on the tpmnt command, then
positioning is absolute with respect to the last tape mark
read or written.
ffp_nv
Number of volumes to position; should always be a positive
number. A volume number of 0 indicates no volume positioning
is to be performed.
ffp_nvs_p
Indicates the direction of volume positioning. The following
values are defined in header file ffio.h:
FP_TPOS_FORW The number of volumes to skip forward, relative
to the current position.
FP_TPOS_BACK The number of volumes to skip backward,
relative to the current position.
FP_TPOS_ABS Specifies an absolute volume number, relative
to the beginning of the volume identifier list
(specified on the tpmnt(1) command.)
ffp_vi
Name of volume identifier to be mounted. A nonzero ffp_vi
field is invalid if ffp_nbs_p is FP_TPOS_FORW or FP_TPOS_BACK
or if ffp_nvs is FP_TPOS_FORW or FP_TPOS_BACK and ffp_nv is
nonzero.
RETURN VALUES
If cmd is FP_BSEEK, ffpos returns the new bit position of the file on
success. For other values of cmd, the ffpos function returns 0 on
success. On failure, it returns -1 and the sw_error field of the stat
structure contains the error number.
SEE ALSOffopen(3C)tpmnt(1) in the UNICOS User Commands Reference Manual, publication
SR-2011
Tape Subsystem User's Guide, publication SG-2051
Application Programmer's Library Reference Manual, publication
SR-2165, for the printed version of this man page.
