#include <ipc/chIpc.h>int grpAllocate(int options, KnCap *groupcap, int stamp);
grpAllocate allocates a port group capability.
groupcap is the returned capability for the port group, and is a pointer to a KnCap structure the members of which are the following:
KnUniqueId ui ; /* entity name */ KnKey key ; /* modification key */
ui is the unique identifier of the port group, used to send messages to the group (see ipcSend(2K) and ipcTarget(2K)). key is the key needed for modification of the group (i.e. inserting or removing ports by grpPortInsert(2K) and grpPortRemove(2K)).
options may have one of the following values, which describe the way in which the port group capability is to be allocated:
The call will return a new unique capability for a port group. stamp is ignored.
The group is a static user port group. The call will not return a new group capability, but a capability of one of the pre-allocated user port group capabilities. The right group is identified by stamp which may vary between 0 and 0xffffffff.
The group is a static system port group. The call will not return a new group name but rather the name of one of the pre-allocated system port group capabilities. The right group is identified by stamp which may vary between 0 and 0xffffffff. This option is only allowed for threads of SYSTEM actors or SUPERVISOR threads.
Static and dynamic groups only differ by the way their name is allocated. They are used (by ipcSend(2K) or ipcCall(2K)) and managed (by grpPortInsert(2K) or grpPortRemove(2K)) in exactly the same way. Static groups are used in order to ease applications binding. Their main property resides in the fact that grpAllocate will always return the same capability for a given value of stamp. The different actors of an application independently invoke grpAllocate. After this operation, some of them insert ports in the group. The others simply send messages to the group. Dynamic groups are used when applications need new groups with unique names. Only one actor of the application invokes grpAllocate. It needs to transmit the group UI to other application actors to allow them to use the group.
Upon successful completion a value of 0 is returned. Otherwise, a negative error code is returned.
The K_STATSYS option is not allowed to the current thread.
Some of the provided data are outside the current actor's address space.
See attributes(5) for descriptions of the following attributes:
|ATTRIBUTE TYPE||ATTRIBUTE VALUE|