fldata() — Retrieve file information

Standards

Standards / Extensions C or C++ Dependencies
Language Environment® 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 filename and other information in the structure info. 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 use 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 use 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.

Note:

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.

Table 1. Elements Returned in fldata_t Data Structure
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:
  • If the file is a DASD data set, memory file, or an HFS file, then __dsname contains the real file name of file opened by ddname
  • If you open by ddname, and the ddname is a concatenation of PDS or PDSE data sets, then __dsname contains the data set name of the first PDS or PDSE. This is because your are only opening the directory of the first PDS or PDSE.
  • If you open by ddname(member) and the ddname is a concatenation of PDS or PDSE data sets, then __dsname contains the data set name of the first PDS or PDSE containing the member.
Otherwise this field is NULL.

The char *__dsname field is allocated internally by the library functions and must be saved before the next call to the fldata() function.

__reserve4 unsigned long Reserved.
Note: The numeric values for the macro names can be found in stdio.h. The meaning of the __noseek_to_seek values are described in topic about using the __amrc structure in z/OS XL C/C++ Programming Guide.

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);
}

Related information