fffcntl(3C)
fffcntl - Performs functions on files opened using flexible file I/O
As shipped in IRIX 6.5. First release of IRIX 6.5.
NAME fffcntl - Performs functions on files opened using flexible file I/O SYNOPSIS #include <ffio.h> UNICOS and UNICOS/mk systems: int fffcntl (int fd, int cmd, [,long *arg, struct ffsw *stat]); IRIX systems: int fffcntl (int fd, int cmd, void *arg, struct ffsw *stat); IMPLEMENTATION UNICOS, UNICOS/mk, and IRIX systems DESCRIPTION The fffcntl function performs a variety of functions on files opened by ffopen or ffopens, using flexible file I/O (FFIO). Arguments are as follows: fd Number returned by function ffopen or ffopens. cmd Specifies values defined in header file ffio.h. See under the next heading, VALUES FOR cmd ARGUMENT. arg The type and value of arg is cmd specific. See preceding descriptions. stat Pointer to the status return structure. Values for cmd Argument The following values can be used for the cmd argument introduced above: FC_ACPTBAD Accepts bad data (valid only for online tape files on UNICOS and UNICOS/mk systems and ER90 files on UNICOS systems.) arg is a pointer to structure ffc_baddata_s, defined in header file ffio.h. This cmd is valid with the tape FFIO layer. The fields of this structure have the following meaning: ffc_bytes Number of bytes of bad data transferred is returned in this field. ffc_maxflag Set this value to 1 if a maximum value is specified in field ffc_maxwords. Set this value to 0 if no maximum value is specified. ffc_maxwords Maximum number of words of bad data to transfer to user's data area. If the number of words of bad data in the block exceed this value, the excess is discarded. ffc_termcnd Position after accepting bad data is shown in this field, as follows: 0 indicates end of block; 1 indicates EOF; 2 indicates EOD; and a value less than 0 indicates that an error occurred. The absolute value is the error number. ffc_uda User data area to receive bad data. FC_ASPOLL Checks for completion of an asynchronous FFIO request. Argument arg is a pointer to a structure of type struct ffsw, which had previously been passed to an asynchronous FFIO request. The purpose of this call is to pass control to the underlying layers to do intermediate processing or cleanup on the request. If the request is complete, fields in the status return structure are set as described under function ffreada(3C). FC_CHECKTP Checks tape position. This value is valid only for online tape files on UNICOS and UNICOS/mk systems and ER90 files on UNICOS systems. arg is a pointer to structure ffc_chktp_s, defined in header file ffio.h. This command is valid with the tape FFIO layer. The fields of this structure have the following meaning: stat The status of the tape, as follows: -1 = No status 0 = At EOV 1 = Tape off reel 2 = Tape mark detected 3 = Blank tape detected The remaining fields are unused. FC_ENDSP Ends special processing. This value is valid only for online tape files on UNICOS and UNICOS/mk systems and ER90 files on UNICOS systems. arg is unused. This function removes the alternate path to tape created by FC_STARTSP. Tape blocks that were held aside are written to tape. This cmd is valid with the tape FFIO layer. FC_CLOSEV Closes volume and mounts next volume in the Volume Identifier list. arg is unused. This value is valid only for online tape files on UNICOS and UNICOS/mk systems and ER90 files on UNICOS systems. The er90 layer is not supported on CRAY T3E systems. This cmd is valid with the following FFIO layers: tape, er90, bufa. FC_GETTP Retrieves information about an opened tape file (valid only for online tape files on UNICOS and UNICOS/mk systems and ER90 files on UNICOS systems. arg is a pointer to structure ffc_gettp_s, defined in header file ffio.h. The er90 layer does not guarantee that records correspond to physical tape blocks. See the assign(1) man page and the Tape Subsystem User's Guide, publication SG-2051 for more information about the er90 FFIO layer. The fields of this structure have the following meaning: ffc_glen Number of words to copy to the array pointed to by field ffc_pa. ffc_synch Synchronization value, as follows: a value of 1 indicates to synchronize the dataset before obtaining position information; a value of 0 means do not synchronize the dataset. This field is ignored if the last operation was a read. It is also invalid to specify this value if end-of-volume (EOV) processing is enabled, and the user has reached EOV but has not started special processing. ffc_pa Address of array that will contain information returned by this function. The values returned in this array are as follows: ffc_pa[0] Current volume identifier. ffc_pa[1] - ffc_pa[6] Characters 1-48 of the path name of the file opened to this tape. ffc_pa[7] Integer file section number. ffc_pa[8] Integer file sequence number. ffc_pa[9] Integer block number relative to tape mark specified in ffc_pa[22]. ffc_pa[10] Integer number of blocks in the library buffer. If additional processing layers have been specified with assign(1) or asgcmd(1), those layers may also hold buffered data, but they will not be included in this field. ffc_pa[11] Integer number of blocks in the IOP or system buffer. ffc_pa[12] Integer device ID or unit number. ffc_pa[13] Device identifier or name. ffc_pa[14] Generic device name. ffc_pa[15] Last device function. ffc_pa[16] Last device status. ffc_pa[17] Data transfer count in bytes. ffc_pa[18] Buffer memory sector count. ffc_pa[19] Partial block bytes in buffer memory. ffc_pa[20] Outstanding sector count. ffc_pa[21] Outstanding block count. ffc_pa[22] User tape mark number, including tape marks embedded in the data. ffc_pa[23] Direction from tape mark in previous word: 0 = after tape mark; 1 = before tape mark. ffc_pa[24] Today's year modulus 100. ffc_pa[25] Today's Julian day. ffc_pa[26] File identifier, up to the first 8 characters. ffc_pa[27] Record format name. ffc_pa[28] Tape density: 1 = 1600 bpi; 2 = 6250 bpi. ffc_pa[29] Maximum block size. ffc_pa[30] Record length. ffc_pa[31] File status: 1 = new; 2 = old; 3 = append. ffc_pa[32] Label type: 1 = no label; 2 = ANSI label; 3 = IBM standard label; 4 = bypass label. ffc_pa[33] Integer file sequence number of first file on volume. ffc_pa[34] Ring status: 0 = ring out; 1 = ring in. ffc_pa[35] Expiration year modulus 100. ffc_pa[36] Expiration Julian day. ffc_pa[37] First volume identifier of file. ffc_pa[38] User end-of-volume status: 0 = EOV processing off; 1 = EOV processing on. ffc_pa[39] User end-of-volume processing status: 0 = not in active EOV processing; 1 = in active EOV processing. ffc_pa[40] User read/write tape mark status: 0 = user read/write tape mark not allowed; 1 = user read/write tape mark is allowed. ffc_pa[41] Block attribute: 'B' = blocked records; 'S' = spanned records, if the record format is 'V', or standard records, if the record format is 'F'; 'R' = blocked and spanned records, if the record format is 'V', blocked and standard records, if the record format is 'F'; '0' = none of the previous values. ffc_pa[42] - ffc_pa[47] File identifier. FC_GETINFO Gets information about the layers connected to this open file. arg is a pointer to structure ffc_info_s. The information returned in this structure is as follows: ffc_flags Flag word containing attributes of the file/connection. These bit masks are defined in header file ffio.h and are set if true, as follows: FFC_STRM Can handle stream I/O. FFC_REC Can handle records. FFC_WEOF Can represent EOF. FFC_WEOD Can represent EOD (always set). FFC_BKSP Can handle backspace. FFC_BKFIL Can handle backfile. FFC_SEEKA Can seek absolute. FFC_SEEKR Can seek relative. FFC_SEEKE Can seek to end. FFC_POSREC Can position by record number. FFC_POSFIL Can position by EOF mark. FFC_RWND Can rewind by seek(x,0,0). FFC_FIXD Can do fixed-length records. FFC_VAR Can do variable-length records. FFC_BINARY Can do binary data. FFC_CODED Can do formatted (character) data. FFC_RDM Can do random I/O (no truncation). FFC_SEQ Can do sequential I/O. FFC_ASYNC Can do asynchronous I/O. (All layers have asynchronous entry points, but this bit tells whether the behavior is actually async.) FFC_WRTRUNC Write implies truncation. FFC_NOTRN Does no transformation on data; no control words are added or subtracted. Data is not changed. ffc_gran Minimum granularity. This is the smallest size in bits of a valid data transfer. For example, the system call layer has an ffc_gran of 8, as it can handle a byte as its smallest unit of data transfer. Some CDC record formats have a granularity of 60. ffc_reclen Valid only for fixed length records. This is the record length in bits. ffc_fd Lowest level file descriptor for the layer that makes system calls. This is not always available, or may not be meaningful for some layers or combinations of layers. This is -1 if no descriptor is available. FC_GETLK Performs an fcntl call with cmd F_GETLK. arg is a pointer to structure flock (defined in sys/fcntl.h), which is used in the fcntl call. Currently supported only by the syscall and system layers, and not for tapes or ER90 devices. FC_GETLKW Performs an fcntl call with cmd F_GETLKW. arg is a pointer to structure flock (defined in sys/fcntl.h), which is used in the fcntl call. Currently supported only by the syscall and system layers, and not for tapes or ER90 devices. FC_IALLOC Performs an ialloc system call. Supported only on UNICOS and UNICOS/mk architectures and only by the syscall and system layers. Not supported for tapes or ER90 devices. arg is a pointer to structure ff_ialloc_struct, defined in the ffio.h file. The ialloc call is made using the following parameters: * The ia_nb element of the structure is the second argument * The ia_flag element of the structure is the third argument * The ia_part element of the structure is the fourth argument * The ia_avl element of the structure is the fifth argument FC_RECALL Awaits completion of an asynchronous FFIO request. Argument arg is a pointer to a structure of type struct ffsw, which is the status return structure of the asynchronous request. Function fffcntl waits for completion of the asynchronous request, if necessary. Fields in the status return structure are set as described under function ffreada(3C). FC_SCRATCH Specifies that a file is to be deleted at close time. The arg argument is a pointer to int. On exit, *arg is set to contain zero or more of the following result bits: SCR_NOFLUSH Set if ffclose processing has been optimized to suppress buffer flushing. SCR_SINGLELINK Set if the file is not a pipe or a tty, has a link count equal to one, and is not a symbolicly linked file. SCR_UNLINKED Set if this fffcntl call has successfully unlinked the file. FC_SETLK Performs an fcntl call with cmd F_SETLK. arg is a pointer to structure flock (defined in sys/fcntl.h), which is used in the fcntl call. Currently supported only by the syscall and system layers, and not for tapes or ER90 devices. FC_SKIPBAD Skips bad data (valid only for online tape files on UNICOS and UNICOS/mk systems and ER90 files on UNICOS systems. arg is a pointer to structure ffc_baddata_s, defined in header file ffio.h. This cmd is valid with the tape FFIO layer. The fields of this structure used by FC_SKIPBAD are as follows; all other fields are unused: ffc_blocks The number of blocks skipped is returned in this field. ffc_termcnd Position after skipping bad data is returned in this field, as follows: 0 indicates end of block; 1 indicates EOF or EOD; and a value less than 0 indicates that an error occurred. The absolute value is the error number. FC_STAT Returns a structure much like the one returned by the fstat (see stat(2)) system call. arg is a pointer to a ffc_stat_s structure (from ffio.h). Fields in this structure are filled in as appropriate by the layers. For the system call layer, all fields are simply retrieved by doing an fstat call. For other layers, such as mr, the size field in the stat structure is modified to reflect the buffered data. Other layers can make similar changes to the basic information from the system for similar reasons. The result is a stat structure that can be used in the same way and for the same purposes as the fstat system call. FC_SETSP Disables special EOV processing. This value is valid only for online tape files on UNICOS and UNICOS/mk systems and ER90 files on UNICOS systems. arg is an integer value that should be set to 0. See ffsetsp(3C) for a description of how to enable special EOV processing. This cmd is valid with the tape FFIO layers. FC_STARTSP Starts special EOV processing. This value is valid only for online tape files on UNICOS and UNICOS/mk systems and ER90 files on UNICOS systems. arg is unused. EOV processing must be enabled prior to starting special EOV processing. This function creates an alternative path to or from a tape. Tape blocks in the pipeline are held aside. Subsequent write operations will go directly to tape; subsequent read operations will come directly from tape (if data is available) or from the blocks in the pipeline. Both read and write operations are performed in FIFO order. After you have read from the blocks in the pipeline, they are unavailable for writing. This cmd is valid with the following tape FFIO layer. FC_TPC_SDBSZ Changes the data block size on an ER90 device. This is valid only when using the tape layer. arg is the requested new block size. This cmd has no effect when it is used with an IBM- compatible tape. Not supported on IRIX systems. FC_TSYNC (Valid only for online tape files on UNICOS and UNICOS/mk systems and ER90 files on UNICOS systems. It requests that the tape file be synchronized. This command is ignored if the last operation was a read. It is also invalid to request synchronization if the end-of-volume (EOV) processing is enabled, and the user has reached EOV but has not started special processing. If the end-of-volume processing is enabled, the user should check to see if EOV was reached after requesting FC_TSYNC (see the description for FC_CHECKTP). In this case, the fffcntl returns without error, but the tape may not be synchronized (that is, data may remain buffered). This cmd is valid with the following FFIO layers: tape, er90, bufa. The er90 layer is not supported on CRAY T3E systems. RETURN VALUES The fffcntl function returns 0 on success. Otherwise, it returns -1 and the sw_error field of the stat structure contains the error number. SEE ALSO fflistio(3C) ffopen(3C), ffreada(3C), ffsetsp(3C), ffwritea(3C) assign(1), asgcmd(1) Tape Subsystem User's Guide, publication SG-2051, for more information about the er90 FFIO layer Application Programmer's Library Reference Manual, publication SR-2165, for the printed version of this man page.