dshm_map(DSHM)

dshm_map -- map DSHM buffer

Synopsis

   #include <dshm.h>
   
   int dshm_map(dshm_handle_t handle, unsigned long buffer_index, const void** bufpp);

Description

dshm_map establishes a mapping to a specified buffer within the DSHM segment attached by handle. The buffer lies at byte offset (buffer_index * buffer_size) within the DSHM object (where buffer_size is as defined by the segment's creation by dshm_get). Upon successful return,*bufpp points to the mapped buffer. The application must initialize *bufpp to the value DSHM_NULL prior to its first use with dshm_map.

The established mapping can be used only by the calling process, except as permitted by use of dshm_updatetlb(DSHM).

If dshm_map returns an error, the map should be considered corrupt. An error indicates a bug, usually a DSHM usage bug in the application. The caller should immediately abort all processes using the map. The map needs to be destroyed and recreated in order to restart the application.

Return values

If dshm_map returns 0, the operation succeeded.

If dshm_map returns -1, an error occurred and the map should be considered corrupt. errno is set to identify the error.

Errors

In the following conditions, dshm_map fails and sets errno to:

EOVERFLOW: The reference count for a map slot exceeds the maximum concurrent mapping count for the map. This strongly suggests an imbalance in dshm_map and dshm_unmap operations.
EDOMAIN: The reference count for a map slot is negative. This strongly suggests an imbalance in dshm_map and dshm_unmap operations.
other: Some other internal inconsistency was discovered. For example, a system call to remap a map slot might have failed.

References

dshm_alignment(DSHM), dshm_attach(DSHM), dshm_bufindex(DSHM), dshm_control(DSHM), dshm_detach(DSHM), dshm_get(DSHM), dshm_minmapsize(DSHM), dshm_reattach(DSHM), dshm_unmap(DSHM), dshm_updatetlb(DSHM)