fldata() — Retrieve file information

Standards

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.

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.

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

• stdio.h
• fopen() — Open a file
• freopen() — Redirect an open file