The routine allocates an amount of virtual memory specified by NMEMB and TYPE. The number of bytes allocated is equal to the number of bytes required to store a single variable of type TYPE, multiplied by NMEMB. A pointer to the allocated storage is returned in PNTR. This pointer can be passed on to other subroutines using the %VAL construct. If the storage cannot be allocated, then PNTR is set to zero, STATUS is set to PSX__NOALL and an error is reported.

CALL PSX_CALLOC( NMEMB, TYPE, PNTR, STATUS )

NMEMB = INTEGER (Given)

TYPE = CHARACTER $\ast$ ( $\ast$ ) (Given)

PNTR = POINTER (Returned)

STATUS = INTEGER (Given and Returned)

CALL PSX_CALLOC( 20, ’_INTEGER’, PNTR, STATUS )
CALL SUB1( %VAL(PNTR), 20, STATUS )
...
SUBROUTINE SUB1( ARRAY, N, STATUS )
INTEGER N
INTEGER ARRAY( N )
...

Generates storage for an array.

The call to PSX_CALLOC allocates storage for a 20 element array of type INTEGER. The pointer to this storage is then passed to subroutine SUB1, where it is accessed as an array of INTEGERs. We assume SUB1 returns without action if STATUS is bad.

• Storage allocated by PSX_CALLOC should be returned by a call to PSX_FREE when it is no longer needed.

• PNTR is declared to be of type POINTER. This is usually represented in FORTRAN as an INTEGER, although any type that uses the same amount of storage would be just as good. The pointer will have been registered for C and FORTRAN use according to the scheme described in SUN/209, allowing its use where pointers are longer than INTEGERs. For portability, the construct %VAL(CNF_PVAL(PNTR)), rather than simply %VAL(PNTR), should be used to pass the pointer to the subroutine. Function CNF_PVAL is described in SUN/209 Section ‘Pointers’.

• If several calls to PSX_CALLOC are made, the space returned by each call is completely separate from that made by any other call. In particular, the program should not assume that the space returned by successive calls is contiguous.

• PSX_CALLOC differs from the POSIX function calloc in that the size of each member to be allocated is specified by a character string (TYPE) rather than as a numerical value. This has been done to increase the portability of the routine.

• The allowed values of TYPE are _INTEGER, _REAL, _DOUBLE, _LOGICAL, _CHAR, _BYTE, _UBYTE, _WORD and _UWORD. The number of bytes allocated for each is as defined in the f77.h header file.

cnf: cnf Calloc, cnfFptr, cnfImpn

• POSIX standard (1988), section 8.1

• ANSI C standard (1989), section 4.10.3.1

Copyright (C) 1991 Science & Engineering Research Council