4.22.2 Message queues API.

The following bindings are exported by the (vicare posix) library. On GNU+Linux systems, for an introduction to the API we must refer to the manual page mq_overview(7) and for the full documentation of each function we must refer to the manual pages. Notice that mq_notify(3) at present is not interfaced.

NOTE The code implementing the interface to POSIX message queues assumes that the descriptor mqd_t is a fixnum. On GNU+Linux systems this value is known to be a file descriptor.

Function: mq-open name oflag mode

Function: mq-open name oflag mode attr

Interface to the C function mq_open(), see the manual page mq_open(3). Create a new message queue or open an existing one. If successful return a message queue descriptor, else raise an exception.

name must be a Scheme string or bytevector holding a pathname in ASCII encoding.

oflag must be a fixnum representing the inclusive OR composition of some of the following flags:

O_RDONLY    O_WRONLY  O_RDWR
O_NONBLOCK  O_CREAT   O_EXCL

mode must be a fixnum representing access permissions for the message queue pathname; it should be an inclusive OR composition of some of the flags:

S_IRUSR   S_IWUSR   S_IXUSR
S_IRGRP   S_IWGRP   S_IXGRP
S_IROTH   S_IWOTH   S_IXOTH

The optional attr must be false or an instance of struct-mq-attr; when false or not given: the queue is created with platform–dependent default attributes. The fields mq_flags and mq_curmsgs are ignored in call to this function.

Function: mq-close mqd

Interface to the C function mq_close(), see the manual page mq_close(3). Close the message queue referenced by the descriptor mqd, which must be a descriptor returned by a previous call to mq-open; notice that the message queue will still exist until it is deleted with mq_unlink(). If successful return unspecified values, else raise an exception.

Function: mq-unlink name

Interface to the C function mq_unlink(), see the manual page mq_unlink(3). Remove the message queue whose name is name, which must be a Scheme string or bytevector representing a pathname in ASCII encoding; the message queue name is removed immediately, while the message queue is removed when all the processes referencing it close their descriptors. If successful return unspecified values, else raise an exception.

Function: mq-send mqd message priority

Interface to the C function mq_send(), see the manual page mq_send(3). Add a message to the queue referenced by the descriptor mqd, which must be a descriptor returned by a previous call to mq-open. If successful return unspecified values, else raise an exception.

message must be a Scheme bytevector representing the message data. priority must be an exact integer, in the range of the C language type unsigned int, representing the priority of the message.

Function: mq-timedsend mqd message priority epoch-timeout

Interface to the C function mq_timedsend(), see the manual page mq_timedsend(3). Add a message to the queue referenced by the descriptor mqd, which must be a descriptor returned by a previous call to mq-open. If successful return unspecified values, else raise an exception.

message must be a Scheme bytevector representing the message data.

priority must be an exact integer, in the range of the C language type unsigned int, representing the priority of the message.

epoch-timeout must be an instance of struct-timespec representing an absolute time since the Epoch: if the queue is in blocking mode, a call to this function will block until the timeout expires waiting to deliver the message. struct-timespec

Function: mq-receive mqd message

Interface to the C function mq_receive(), see the manual page mq_receive(3). Remove the oldest message with the highest priority from the message queue referenced by mqd, which must be a descriptor returned by a previous call to mq-open. If successful return two values: an exact integer representing the number of bytes in the message, a non–negative exact integer representing the priority of the message; else raise an exception.

message must be a Scheme bytevector providing the buffer in which the function will write the received message; its length must be greater than the maximum message length specified in the queue attributes.

Function: mq-timedreceive mqd message epoch-timeout

Interface to the C function mq_timedreceive(), see the manual page mq_timedreceive(3). Remove the oldest message with the highest priority from the message queue referenced by mqd, which must be a descriptor returned by a previous call to mq-open. If successful return two values: an exact integer representing the number of bytes in the message, a non–negative exact integer representing the priority of the message; else raise an exception.

message must be a Scheme bytevector providing the buffer in which the function will write the received message; its length must be greater than the maximum message length specified in the queue attributes.

epoch-timeout must be an instance of struct-timespec representing an absolute time since the Epoch: if the queue is in blocking mode, a call to this function will block until the timeout expires waiting to receive the message. struct-timespec

Function: mq-setattr mqd new-attr

Function: mq-setattr mqd new-attr old-attr

Interface to the C function mq_setattr(), see the manual page mq_setattr(3). Modify the attributes of the message queue referenced by mqd, which must be a descriptor returned by a previous call to mq-open. If successful return an instance of struct-mq-attr representing the old attributes, else raise an exception.

The new values are read from new-attr, which must be an instance of struct-mq-attr. On GNU+Linux: the only attribute that can be modified is mq_flags, all the other values are ignored (last verified on Jul 7, 2012).

The old values are stored in old-attr, which must be an instance of struct-mq-attr; when old-attr is not given: a new instance of struct-mq-attr is internally created. old-attr or the new instance are the return value of this function.

Function: mq-getattr mqd

Function: mq-getattr mqd attr

Interface to the C function mq_getattr(), see the manual page mq_getattr(3). Retrieve the attributes of the message queue referenced by mqd, which must be a descriptor returned by a previous call to mq-open. If successful return an instance of struct-mq-attr representing the old attributes, else raise an exception.

The values are stored in attr, which must be an instance of struct-mq-attr; when attr is not given: a new instance of struct-mq-attr is internally created. attr or the new instance are the return value of this function.