Shared memory services. More...

Collaboration diagram for Shared memory services.:

Functions
int	shm_open (const char *name, int oflags, mode_t mode)
	Open a shared memory object. More...

int	close (int fd)
	Close a file descriptor. More...

int	shm_unlink (const char *name)
	Unlink a shared memory object. More...

int	ftruncate (int fd, off_t len)
	Truncate a file or shared memory object to a specified length. More...

void *	mmap (void *addr, size_t len, int prot, int flags, int fd, off_t off)
	Map pages of memory. More...

int	munmap (void *addr, size_t len)
	Unmap pages of memory. More...

Detailed Description

Shared memory services.

Shared memory objects are memory regions that can be mapped into processes address space, allowing them to share these regions as well as to share them with kernel-space modules.

Shared memory are also the only mean by which anonymous POSIX skin synchronization objects (mutexes, condition variables or semaphores) may be shared between kernel-space modules and user-space processes, or between several processes.

Function Documentation

int close ( int fd )

Close a file descriptor.

This service closes the file descriptor fd. In kernel-space, this service only works for file descriptors opened with shm_open(), i.e. shared memory objects. A shared memory object is only destroyed once all file descriptors are closed with this service, it is unlinked with the shm_unlink() service, and all mappings are unmapped with the munmap() service.

Parameters

fd	file descriptor.

Return values

0	on success;
-1	with errno set if: EBADF, fd is not a valid file descriptor (in kernel-space, it was not obtained with shm_open()); EPERM, the caller context is invalid.

Valid contexts:

kernel module initialization or cleanup routine;
kernel-space cancellation cleanup routine;
user-space thread (Xenomai threads switch to secondary mode);
user-space cancellation cleanup routine.

See also: Specification.

Examples:: bufp-label.c, bufp-readwrite.c, iddp-label.c, iddp-sendrecv.c, pipe.c, and rtcan_rtt.c.

Referenced by shm_open().

int ftruncate	(	int	fd,
		off_t	len
	)

Truncate a file or shared memory object to a specified length.

When used in kernel-space, this service set to len the size of a shared memory object opened with the shm_open() service. In user-space this service falls back to Linux regular ftruncate service for file descriptors not obtained with shm_open(). When this service is used to increase the size of a shared memory object, the added space is zero-filled.

Shared memory are suitable for direct memory access (allocated in physically contiguous memory) if O_DIRECT was passed to shm_open.

Shared memory objects may only be resized if they are not currently mapped.

Parameters

fd	file descriptor;
len	new length of the underlying file or shared memory object.

Return values

0 on success;

-1

with errno set if:

EBADF, fd is not a valid file descriptor;
EPERM, the caller context is invalid;
EINVAL, the specified length is invalid;
EINVAL, the architecture can not honour the O_DIRECT flag;
EINTR, this service was interrupted by a signal;
EBUSY, fd is a shared memory object descriptor and the underlying shared memory is currently mapped;
EFBIG, allocation of system memory failed.

Valid contexts:

kernel module initialization or cleanup routine;
user-space thread (Xenomai threads switch to secondary mode).

See also: Specification.

References xnheap_alloc(), xnheap_free(), and xnheap_set_label().

Referenced by shm_open().

void* mmap	(	void *	addr,
		size_t	len,
		int	prot,
		int	flags,
		int	fd,
		off_t	off
	)

Map pages of memory.

This service allow shared memory regions to be accessed by the caller.

When used in kernel-space, this service returns the address of the offset off of the shared memory object underlying fd. The protection flags prot, are only checked for consistency with fd open flags, but memory protection is unsupported. An existing shared memory region exists before it is mapped, this service only increments a reference counter.

The only supported value for flags is MAP_SHARED.

When used in user-space, this service maps the specified shared memory region into the caller address-space. If fd is not a shared memory object descriptor (i.e. not obtained with shm_open()), this service falls back to the regular Linux mmap service.

Parameters

addr	ignored.
len	size of the shared memory region to be mapped.
prot	protection bits, checked in kernel-space, but only useful in user-space, are a bitwise or of the following values: PROT_NONE, meaning that the mapped region can not be accessed; PROT_READ, meaning that the mapped region can be read; PROT_WRITE, meaning that the mapped region can be written; PROT_EXEC, meaning that the mapped region can be executed.
flags	only MAP_SHARED is accepted, meaning that the mapped memory region is shared.
fd	file descriptor, obtained with shm_open().
off	offset in the shared memory region.

Return values

0 on success;

MAP_FAILED

with errno set if:

EINVAL, len is null or addr is not a multiple of PAGE_SIZE;
EBADF, fd is not a shared memory object descriptor (obtained with shm_open());
EPERM, the caller context is invalid;
ENOTSUP, flags is not MAP_SHARED;
EACCES, fd is not opened for reading or is not opend for writing and PROT_WRITE is set in prot;
EINTR, this service was interrupted by a signal;
ENXIO, the range [off;off+len) is invalid for the shared memory region specified by fd;
EAGAIN, insufficient memory exists in the system heap to create the mapping, increase CONFIG_XENO_OPT_SYS_HEAPSZ.

Valid contexts:

kernel module initialization or cleanup routine;
user-space thread (Xenomai threads switch to secondary mode).

See also: Specification.

int munmap	(	void *	addr,
		size_t	len
	)

Unmap pages of memory.

This service unmaps the shared memory region [addr;addr+len) from the caller address-space.

When called from kernel-space the memory region remain accessible as long as it exists, and this service only decrements a reference counter.

When called from user-space, if the region is not a shared memory region, this service falls back to the regular Linux munmap() service.

Parameters

addr	start address of shared memory area;
len	length of the shared memory area.

Return values

0	on success;
-1	with errno set if: EINVAL, len is null, addr is not a multiple of the page size or the range [addr;addr+len) is not a mapped region; ENXIO, addr is not the address of a shared memory area; EPERM, the caller context is invalid; EINTR, this service was interrupted by a signal.

Valid contexts:

kernel module initialization or cleanup routine;
kernel-space cancellation cleanup routine;
user-space thread (Xenomai threads switch to secondary mode);
user-space cancellation cleanup routine.

See also: Specification.

int shm_open	(	const char *	name,
		int	oflags,
		mode_t	mode
	)

Open a shared memory object.

This service establishes a connection between a shared memory object and a file descriptor. Further use of this descriptor will allow to dimension and map the shared memory into the calling context address space.

One of the following access mode should be set in oflags:

O_RDONLY, meaning that the shared memory object may only be mapped with the PROT_READ flag;
O_WRONLY, meaning that the shared memory object may only be mapped with the PROT_WRITE flag;
O_RDWR, meaning that the shared memory object may be mapped with the PROT_READ | PROT_WRITE flag.

If no shared memory object named name exists, and oflags has the O_CREAT bit set, the shared memory object is created by this function.

If oflags has the two bits O_CREAT and O_EXCL set and the shared memory object alread exists, this service fails.

If oflags has the bit O_TRUNC set, the shared memory exists and is not currently mapped, its size is truncated to 0.

If oflags has the bit O_DIRECT set, the shared memory will be suitable for direct memory access (allocated in physically contiguous memory).

name may be any arbitrary string, in which slashes have no particular meaning. However, for portability, using a name which starts with a slash and contains no other slash is recommended.

Parameters

name	name of the shared memory object to open;
oflags	flags.
mode	ignored.

Returns

a file descriptor on success;

-1 with errno set if:

ENAMETOOLONG, the length of the name argument exceeds 64 characters;
EEXIST, the bits O_CREAT and O_EXCL were set in oflags and the shared memory object already exists;
ENOENT, the bit O_CREAT is not set in oflags and the shared memory object does not exist;
ENOSPC, insufficient memory exists in the system heap to create the shared memory object, increase CONFIG_XENO_OPT_SYS_HEAPSZ;
EPERM, the caller context is invalid;
EINVAL, the O_TRUNC flag was specified and the shared memory object is currently mapped;
EMFILE, too many descriptors are currently open.

Valid contexts:

kernel module initialization or cleanup routine;
user-space thread (Xenomai threads switch to secondary mode).

See also: Specification.

References close(), and ftruncate().

int shm_unlink ( const char * name )

Unlink a shared memory object.

This service unlinks the shared memory object named name. The shared memory object is not destroyed until every file descriptor obtained with the shm_open() service is closed with the close() service and all mappings done with mmap() are unmapped with munmap(). However, after a call to this service, the unlinked shared memory object may no longer be reached with the shm_open() service.

Parameters

name	name of the shared memory obect to be unlinked.

Return values

0	on success;
-1	with errno set if: EPERM, the caller context is invalid; ENAMETOOLONG, the length of the name argument exceeds 64 characters; ENOENT, the shared memory object does not exist.

Valid contexts:

kernel module initialization or cleanup routine;
kernel-space cancellation cleanup routine;
user-space thread (Xenomai threads switch to secondary mode);
user-space cancellation cleanup routine.

See also: Specification.

Functions

Detailed Description

Function Documentation