FFFCNTL(3C) Last changed: 2-25-98
NAMEfffcntl - 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 ALSOfflistio(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.
