flocate - Explicitly position an ISAM file (record I/O)

Definition

#include <stdio.h>

int flocate(FILE *fp, void *key, size_t keylen, int option);

flocate explicitly positions an ISAM file with record I/O. flocate changes the current position of the read/write pointer of the file with file pointer fp according to the following:
key value key,
key length keylen and
option option (_KEY_FIRST, _KEY_LAST, _KEY_EQ, _KEY_GE).

Parameters

FILE *fp

File pointer of an ISAM file opened in the mode "type=record,forg=key" (cf. fopen/open64, freopen/freopen64).

void *key

Pointer to an area containing the key value.

size_t keylen

Length of the key value. The value must not be zero.

If keylen is less than the key length of the file, then flocate internally pads out the key value with binary zeros to the key length of the file and uses this generated key as the basis for positioning.
If keylen is greater than the key length of the file, flocate internally truncates the key value from the right to the key length of the file and uses this shortened key as the basis for positioning.

int option

This parameter may contain the following values defined in <stdio.h>:

_KEY_FIRST	Positions the read/write pointer to beginning of file. The key and keylen parameters are ignored. Positioning works even if the file is empty.
_KEY_LAST	Positions the read/write pointer to end of file. The key and keylen parameters are ignored. Positioning works even if the file is empty.
_KEY_EQ	Positions the read/write pointer on the first record with the specified key key.
_KEY_GE	Positions the read/write pointer on the first record with a key value greater than or equal to the specified key key.

Return val.

0

If the record with the specified key exists.

> 0

If the record does not exist

EOF

If an error has occurred.

Notes

If the call was error-free (return values 0 or > 0), the EOF flag of the file is reset.

If the specified key value is not present in the file (return value > 0) the current position of the read/write pointer remains unchanged. Sole exception: if at the time of the flocate call the file is positioned on the second or higher key of a group of records with identical keys, then flocate positions the file on the first record after this group.

In ISAM files with key duplication, flocate cannot be used to position on the second or higher record of a group with identical keys. This can only be done by sequential reading or deleting.
With flocate it is only possible to position on the first record or after the last record of such a group.

See also

fdelrec, fgetpos, fgetpos64, fsetpos, fsetpos64, fopen, open64, freopen, freopen64