ffpos(3C)
ffpos - Positions files opened using flexible file I/O
As shipped in IRIX 6.5. First release of IRIX 6.5.
NAME ffpos - 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 ALSO ffopen(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.