PURPOSE

Fgetalloc, Fgetalloc32 - allocate space and get copy of field occurrence

SYNOPSIS

#include <stdio.h>
#include "fml.h"
char *
Fgetalloc(FBFR *fbfr, FLDID fieldid, FLDOCC oc, FLDLEN *extralen)
#include "fml32.h"
char *
Fgetalloc32(FBFR32 *fbfr, FLDID32 fieldid, FLDOCC32 oc, FLDLEN32 *extralen)

DESCRIPTION

Like Fget(3fml), Fgetalloc(\|) finds and makes a copy of a buffer field, but it acquires space for the field via a call to malloc(3) (in UNIX System programmer's reference manuals). fbfr is a pointer to a fielded buffer. fieldid is a field identifier. oc is the occurrence number of the field. The last argument to Fgetalloc(\|), extralen, provides an extra amount of space to be acquired in addition to the field value size. It can be used if the retrieved value is to be expanded before re-insertion into the fielded-buffer. If extralen is NULL, then no additional space is allocated and the actual length is not returned. It is the caller's responsibility to free(3) space acquired by Fgetalloc(\|). The buffer will be aligned properly for any field type.

Fgetalloc32 is used with 32-bit FML.

RETURN VALUES

In the SYNOPSIS

section above the return value to Fgetalloc(\|) is described as a character pointer data type (char * in C). Actually, the pointer returned points to an object that has the same type as the stored type of the field.

This function returns NULL on error and sets Ferror to indicate the error condition.

ERRORS

Under the following conditions, Fgetalloc() fails and sets Ferror to:

[FALIGNERR]

"fielded buffer not aligned" The buffer does not begin on the proper boundary.

[FNOTFLD]

"buffer not fielded" The buffer is not a fielded buffer or has not been initialized by Finit().

[FNOTPRES]

"field not present" A field occurrence is requested but the specified field and/or occurrence was not found in the fielded buffer.

[FBADFLD]

"unknown field number or type" A field identifier is specified which is not valid.

[FMALLOC]

"malloc failed" Allocation of space dynamically using malloc(3) failed.

SEE ALSO

Fintro(3fml),
CFget(3c),
Fget(3fml),
Fgetlast(3fml),
Fgets(3fml),
Fgetsa(3fml)
free(3), malloc(3) in a UNIX System reference manual