fldata() — Retrieve file information
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
Language Environment® Runtime library extensions
|
both |
Format
#include <stdio.h>
int fldata(FILE *file, char *filename, fldata_t *info);
#define _OPEN_SYS_UNLOCKED_EXT 1
#include <stdio.h>
int fldata_unlocked(FILE *file, char *filename, fldata_t *info);
General description
Retrieves information about an open stream pointed to by file. It returns the file name in the buffer that is pointed by
filename
and other information in the structure that is pointed
by info
. The file name buffer and other information structure
are user provided. The file name returned in filename is the name
specified in fopen()
or freopen()
. If the file is opened with a
ddname (for example, fopen("DD:A","w"))
), then the
filename field will contain the ddname used to
open the file, prefixed with dd:
. If the file is a DASD data set or a memory file,
the field __dsname
contains the dsname. If the file is an HFS file, the field
__dsname contains the path name. For all other files, it is NULL.
After a failure, the contents of the information structure are indeterminate.
To avoid infringing on the user's name space, this nonstandard function has two names. One name is prefixed with two underscore characters, and one name is not. The name without the prefix underscore characters is exposed only when you specify LANGLVL(EXTENDED).
To use this function, you must either invoke the function using its external entry point name (that is, the name that begins with two underscore characters), or compile with LANGLVL(EXTENDED). When you compile with LANGLVL(EXTENDED), any relevant information in the header is also exposed.
For full details about filename considerations, see one of the “Opening Files” topics in z/OS XL C/C++ Programming Guide.
If fldata is the first reference to a standard stream, a call to the
fldata()
function opens the stream.
See Table 1.
- A file name of NULL indicates that no file name will be returned.
- FILENAME_MAX is recommended for the size of the file name buffer.
The table Elements Returned in fldata_t Data Structure
(below) describes the fields in
the fldata_t data structure. For further details, see z/OS XL C/C++ Programming Guide.
fldata_unlocked()
is functionally equivalent to fldata()
with
the exception that it is not thread-safe. This function can safely be used in a multithreaded
application if and only if it is called while the invoking thread owns the (FILE*) object, as is the
case after a successful call to either the flockfile()
or
ftrylockfile()
function.
Special behavior for POSIX C: Under z/OS®
UNIX services, if there had been an exec to an
application that invokes fldata()
, the standard streams are opened at the time of
the exec. Thus fldata()
does not attempt to open them again.
Returned value
If successful, fldata()
returns 0.
If unsuccessful, fldata()
returns nonzero.
Element | Data Type | General Description |
---|---|---|
__recfmF:1 | unsigned int | Indicates whether it has fixed-length records. |
__recfmV:1 | unsigned int | Indicates whether it has variable-length records. |
__recfmU:1 | unsigned int | Indicates whether it has undefined-length records. |
__recfmS:1 | unsigned int | Indicates whether it has either standard (if fixed-length) or spanned (if variable-length) records. |
__recfmBlk:1 | unsigned int | Indicates whether it has blocked records. |
__recfmASA:1 | unsigned int | Indicates whether it has ASA print-control characters. |
__recfmM:1 | unsigned int | Indicates whether it has machine print-control codes. |
__dsorgPO:1 | unsigned int | Indicates whether it is a partitioned data set. |
__dsorgPDSmem:1 | unsigned int | Indicates whether a file is a member. |
__dsorgPDSdir:1 | unsigned int | Indicates whether a file is a PDS or PDSE directory. |
__dsorgPS:1 | unsigned int | Indicates whether it is a sequential data set. |
__dsorgConcat:1 | unsigned int | Indicates whether it is a sequentially concatenated file. |
__dsorgMem:1 | unsigned int | Indicates whether it is a memory file. |
__dsorgHiper:1 | unsigned int | Indicates whether it is a memory file in hiperspace. |
__dsorgTemp:1 | unsigned int | Indicates whether it is a temporary file created by tmpfile(). |
__dsorgVSAM:1 | unsigned int | Indicates whether it is a VSAM file. |
__dsorgHFS: | unsigned int | Indicates whether it is an HFS file. |
__openmode:2 | unsigned int | Values are __TEXT, __BINARY, __RECORD, __BLOCKED. |
__modeflag:4 | unsigned int | Values are __APPEND, __READ, __UPDATE, __WRITE. These macros can be added together to determine the value; for example, a file opened with mode a+ will have the value __APPEND + __UPDATE. |
__dsorgPDSE:1 | unsigned int | Indicates whether a file is a PDSE. |
__vsamRLS:3 | unsigned int | Returned values are __NORLS, __RLS, __TVS. |
__recfmB:1 | unsigned int | Indicates whether it was allocated with blocked records |
__reserve2:3 | unsigned int | Reserved bits. |
__device | char | Returned values are __DISK, __TERMINAL, __PRINTER, __TAPE, __TDQ, __DUMMY, __OTHER, __MEMORY, __MSGFILE, __HFS, __HIPERSPACE, __MSGRTN. |
__blksize | unsigned long | Total block size of the file, including all control information needed in the block. |
__maxreclen | unsigned long | Maximum length of the data in the record, including ASA control characters, if present. |
__vsamtype | unsigned short | Returned values are __NOTVSAM, __ESDS, __KSDS, __RRDS, __ESDS_PATH,
__KSDS_PATH. Note: Valid only if __dsorgVSAM is set.
|
__vsamkeylen | unsigned long | Length of VSAM key (if any). Note: Valid only if __dsorgVSAM
is set.
|
__vsamRKP | unsigned long | Key position. Note: Valid only if __dsorgVSAM is set.
|
__access_method | uint8_t | Identifies the access method used for the data
set. Values include: __AM_UNSPEC
__AM_BSAM __AM_QSAM Note: Valid only if __dsorgPS or __dsorgPO is set.
|
__noseek_to_seek | uint8_t | Identifies the reason noseek was changed to
seek. Values include: __AM_BSAM_NOSWITCH
__AM_BSAM_UPDATE __AM_BSAM_BSAMWRITE __AM_BSAM_FBS_APPEND __AM_BSAM_LRECLX __AM_BSAM_PARTITIONED_DIRECTORY __AM_BSAM_PARTITIONED_INDIRECT Note: Valid only if __dsorgPS
or __dsorgPO is set.
|
__dsname | char * | The contents of this field is determined by the following:
The char *__dsname field is allocated internally by the
library functions and must be saved before the next call to the |
__reserve4 | unsigned long | Reserved. |
Example
#include <stdio.h>
int main(void)
{
FILE *stream;
char filename[100];
fldata_t fileinfo;
int rc;
stream = fopen("myfile.dat","rb+");
⋮
rc = fldata(stream, filename, &fileinfo);
if (rc != 0)
printf("fldata failed\n");
else
printf("filename is %s\n",filename);
}