 |
Index for
Section 3 |
|
 |
Alphabetical
listing for I |
|
 |
Bottom of
page |
|
imc_asalloc(3)
NAME
imc_asalloc - Allocates a region of Memory Channel address space on a
specified logical rail
LIBRARY
Memory Channel API library (libimc.a)
SYNOPSIS
#include <sys/imc.h>
int imc_asalloc (
imc_key_t key,
imc_size_t size,
imc_perm_t perm,
int flag,
imc_asid_t *id,
int logical_rail );
PARAMETERS
key Specifies an application-specific key that refers to the region.
Other processes that allocate the region also specify this key.
This ensures that access to the region is coordinated on a
clusterwide basis.
size Specifies the size, in bytes, of the Memory Channel address space
region to be allocated. The imc_asalloc() function allocates
address space, in pages, and it rounds up the value specified by
the size parameter accordingly.
perm Specifies the read and write permissions for the allocated
region. The permission code is similar to the UNIX permission
convention, except that there is no execute flag. The value of
the perm parameter is obtained by carrying out a logical OR
operation on the following values:
IMC_URW User read and write
IMC_UR User read
IMC_UW User write
IMC_GRW Group read and write
IMC_GR Group read
IMC_GW Group write
IMC_ORW Other read and write
IMC_OR Other read
IMC_OW Other write
flag Specifies whether the region is to be mapped into all hosts on
the cluster at the time of allocation. The flag parameter has the
following values:
IMC_COHERENT
Allocate a coherent region. When other processes
allocate and attach this region, they will see all
updates to the region since the region was created.
When the IMC_COHERENT flag is specified, the physical
pages that underlie the region are nonpageable on all
hosts.
ZERO (0) Do not allocate a coherent region. When processes on
other hosts allocate and attach the region, they will
see all updates to the region from then on. However,
the initial contents of the region are indeterminate.
id Returns an identifier that uniquely identifies the allocated
Memory Channel region.
logical_rail
Specifies the Memory Channel logical rail to use. The first
logical rail is numbered 0, the second logical rail is numbered
1, and so on, up to a maximum defined by a constant,
IMC_MAXRAILS.
DESCRIPTION
The imc_asalloc() function allocates a region of Memory Channel address
space on a specified logical rail. If the function successfully allocates
the region, it returns the region identifier in the id parameter. If the
function call is unsuccessful, the value of the id parameter is undefined.
If a region with the key specified in the key parameter has already been
allocated on the cluster, then the imc_asalloc() function returns the
identifier of that region, and does not allocate a new region. Individual
applications should define their own naming scheme for keys. The use of
meaningful application-specific keys is recommended.
It is possible for multiple processes on a given host to allocate the same
region of Memory Channel address space. When multiple processes allocate a
region, the permissions specified by each process must be compatible
clusterwide; otherwise, an error condition will result.
The permissions associated with a region are determined by the first
process to allocate the region.
When processes on multiple hosts allocate a region, the initial contents of
the region might not be the same on all hosts. This situation can arise
because a process that has mapped the same Memory Channel region for
transmit might update the contents of the region before other processes map
the region for receive. To ensure that the region is coherent on all hosts
in the cluster, specify the IMC_COHERENT flag when allocating the region.
The Memory Channel API library maintains the total amount of available
Memory Channel address space as a clusterwide resource. If the
imc_asalloc() function tries to allocate a region that exceeds the amount
of address space available, an error condition will result.
RETURN VALUES
The imc_asalloc() function returns one of the following values:
IMC_SUCCESS
Normal successful completion.
IMC_BADPARM
An invalid parameter was specified in the call to the
imc_asalloc() function.
IMC_BADRAIL
The logical rail number specified in the call to the imc_asalloc
function is invalid, or the logical rail is inactive.
IMC_BADSIZE
The specified region is already allocated, and the size of the
region as specified in this call to the imc_asalloc() function
does not match the size specified in the previous call.
IMC_COHERENCYERR
The specified region is already allocated, and the value of the
flag parameter IMC_COHERENT specified in this call to the
imc_asalloc() function does not match the value specified in the
previous call.
IMC_MCFULL
There is not enough Memory Channel address space to allocate the
amount specified by the size parameter.
IMC_NOMEM There is insufficient local memory available to allocate the
region.
IMC_NORESOURCES
There are insufficient Memory Channel data structures available
to allocate the region.
IMC_NOTINIT
This host has not been initialized to use the Memory Channel API
library.
IMC_PERMIT
The specified region is already allocated, with a permission code
that is incompatible with the code specified in the perm
parameter.
IMC_PRIOR The region has already been allocated by this process.
IMC_WRONGRAIL
The specified region has already been allocated by a process on
the cluster, using the same key, on a specific logical rail; the
specified region cannot now be allocated on a different logical
rail.
RELATED INFORMATION
Introduction: imc(3)
Commands: imc_init(1), imcs(1)
Functions: imc_api_init(3), imc_asattach(3), imc_asattach_ptp(3),
imc_asdealloc(3), imc_asdetach(3), imc_bcopy(3)
Cluster Highly Available Applications
|
Index for
Section 3 |
|
|
Alphabetical
listing for I |
|
 |
Top of
page |
|