.TH "posix\-mq\-rb" "1" "Jan 1, 2010" "posix\-mq\-rb User Manual" "" .SH NAME .PP posix\-mq\-rb \- command\-line interface for POSIX message queues .SH SYNOPSIS .PP MQUEUE=/name posix\-mq\-rb COMMAND [\f[I]OPTIONS\f[]] [\f[I]ARGUMENTS\f[]] .SH DESCRIPTION .PP A command\-line interface for manipulating POSIX message queues. It is useful for testing and debugging applications using POSIX message queues. .SH COMMANDS .PP \f[I]create\f[] \- create a new message queue .PP \f[I]attr\f[] \- output attributes of the message queue .PP \f[I]send\f[] \- insert a message into the queue from stdin or the command\-line .PP \f[I]receive\f[] \- take a message from the queue and outputs it to stdout .PP \f[I]wait\f[] \- sleep until a message is available in the queue .PP \f[I]unlink\f[] \- unlink the message queue .SH CREATE USAGE .PP The \f[I]create\f[] command accepts the following options: .TP .B \-x, \-\-exclusive This causes queue creation to fail if the queue exists. .RS .RE .TP .B \-m, \-\-mode MODE The MODE to open the file under, the actual mode of the queue will be AND\-ed with the current umask (like open(2)). .RS .RE .TP .B \-c, \-\-maxmsg COUNT The maximum messages in the queue. The default and limit of this value is system\-dependent. This must be specified if \-\-msgsize is also specified. .RS .RE .TP .B \-s, \-\-msgsize BYTES The maximum size of an individual message. The default and limit of this value is system\-dependent. This must be specified if \-\-maxmsg is also specified. .RS .RE .SH ATTR USAGE .PP The \f[I]attr\f[] command takes no special options nor command\-line arguments. The output format of this command is suitable for "eval" in shell scripts. Sample output is below: .IP .nf \f[C] \ \ \ \ flags=0 \ \ \ \ maxmsg=10 \ \ \ \ msgsize=8192 \ \ \ \ curmsgs=3 \f[] .fi .PP See mq_getattr(3) for information on the meaning of the fields. .SH SEND USAGE .PP The \f[I]send\f[] command will read a message from standard input if no command\-line arguments are given. If command\-line arguments are given, each argument is considered its own message and will be inserted into the queue separately. .PP The following command\-line arguments are accepted: .TP .B \-n, \-\-nonblock Exit immediately with error if the message queue is full. Normally posix\-mq\-rb(1) will block until the queue is writable or interrupted. This may not be used in conjunction with \-\-timeout . .RS .RE .TP .B \-t, \-\-timeout SECONDS Timeout and exit with error after SECONDS if the message queue is full. This may not be used in conjunction with \-\-nonblock. .RS .RE .TP .B \-p, \-\-priority PRIORITY Specify an integer PRIORITY, this value should be 0 through 31 (inclusive) for portability across POSIX\-compliant systems. The default priority is 0. .RS .RE .SH RECEIVE USAGE .PP The \f[I]receive\f[] command will output message to standard output. It will read a message from standard input if no command\-line arguments are given. If command\-line arguments are given, each argument is considered its own message and will be inserted into the queue separately. .PP The following command\-line arguments are accepted: .TP .B \-n, \-\-nonblock Exit immediately with error if the message queue is empty. Normally posix\-mq\-rb(1) will block until the queue is readable or interrupted. This may not be used in conjunction with \-\-timeout . .RS .RE .TP .B \-t, \-\-timeout SECONDS Timeout and exit with error after SECONDS if the message queue is empty. This may not be used in conjunction with \-\-nonblock. .RS .RE .TP .B \-p, \-\-priority Output the priority of the received message to stderr in the following format: .RS .IP .nf \f[C] priority=3 \f[] .fi .PP The priority is an unsigned integer. .RE .SH WAIT USAGE .PP The \f[I]wait\f[] command will cause posix\-mq\-rb(1) to sleep until a message is available in the queue. Only one process may wait on an empty queue, posix\-mq\-rb(1) will exit with an error if there is another waiting process. .PP It takes no arguments and accepts the following options: .TP .B \-t, \-\-timeout SECONDS Timeout and exit with error after SECONDS if the message queue is empty. .RS .RE .SH UNLINK USAGE .PP The \f[I]unlink\f[] command prevents further opening and use of the current queue. Existing processes with the queue open may continue to operate on the queue indefinitely. If a new queue is created with the same name, the created queue is a different queue from the unlinked queue. See mq_unlink(3) for more information. .SH GENERAL OPTIONS .TP .B \-q Do not show warning/error messages, suitable for scripting. .RS .RE .TP .B \-h, \-\-help Show summary usage .RS .RE .SH ENVIRONMENT .PP All commands rely on the MQUEUE environment variable. The value of MQUEUE should always be prefixed with a slash ("/") for portability. .SH DIAGNOSTICS .PP Exit status is normally 0. Exit status is 2 if a timeout occurs, 1 for all other errors. .PP Under FreeBSD, the mq_* system calls are not available unless you load the mqueuefs(5) kernel module: .IP .nf \f[C] \ \ \ \ kldload\ mqueuefs \f[] .fi .SH SEE ALSO .IP \[bu] 2 mq_overview(7) (http://kernel.org/doc/man-pages/online/pages/man7/mq_overview.7.html) .IP \[bu] 2 mqueuefs(5) (http://freebsd.org/cgi/man.cgi?query=mqueuefs) .SH AUTHORS Ruby POSIX MQ hackers .