$isfilevalid()

Synopsis

$isfilevalid(<file handle>)

Description

Returns true if the handle is present in EPIC's open-file registry, and false otherwise. This includes handles returned by open or exec. Once close removes a handle, it is no longer valid.

These are EPIC file handles, not operating-system file descriptors, server references, or filenames. A raw descriptor number is not a substitute; if it happens to equal a registered EPIC handle, the function tests that EPIC handle.

The first argument is converted to an integer; additional arguments are ignored. Conversion accepts decimal, hexadecimal, and leading-zero octal. Nonnumeric text converts to zero, which is not an issued file handle. Missing input returns the empty string.

Validity only means that EPIC recognizes the handle. It does not check read/write mode, EOF, stream errors, peer availability, or whether the next read or write operation will succeed. Archive-backed input handles also qualify; this does not make operations requiring an ordinary file stream available on them.

Returns

Examples

$isfilevalid($file_handle)
$isfilevalid(-1)

The first checks a previously stored handle. The second returns 0, as -1 is not an issued handle. The function performs no I/O and does not close or change the stream.

History

This function first appeared in EPIC4-1.1.6.

Source

Registered and implemented as function_isfilevalid in source/functions.c. Handle allocation, file_valid, lookup, and removal are in source/files.c; numeric conversion is in source/ircaux.c.