.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 \[lq]eval\[rq] in shell scripts. Sample output is below: .PP \f[CR] \ \ \ \ flags=0 \ \ \ \ maxmsg=10 \ \ \ \ msgsize=8192 \ \ \ \ curmsgs=3 \f[] .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 .PP \f[CR] priority=3 \f[] .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 (\[lq]/\[rq]) 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: .PP \f[CR] \ \ \ \ kldload\ mqueuefs \f[] .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 AUTHOR Ruby POSIX MQ hackers