Documentation/posix-mq-rb.1.txt

   1 % posix-mq-rb(1) posix-mq-rb User Manual
   2 % Ruby POSIX MQ hackers <ruby.posix.mq@librelist.com>
   3 % Jan 1, 2010
   4
   5 # NAME
   6
   7 posix-mq-rb - command-line interface for POSIX message queues
   8
   9 # SYNOPSIS
  10
  11 MQUEUE=/name posix-mq-rb COMMAND [*OPTIONS*] [*ARGUMENTS*]
  12
  13 # DESCRIPTION
  14
  15 A command-line interface for manipulating POSIX message queues.  It is
  16 useful for testing and debugging applications using POSIX message
  17 queues.
  18
  19 # COMMANDS
  20
  21 *create* - create a new message queue
  22
  23 *attr* - output attributes of the message queue
  24
  25 *send* - insert a message into the queue from stdin or the command-line
  26
  27 *receive* - take a message from the queue and outputs it to stdout
  28
  29 *wait* - sleep until a message is available in the queue
  30
  31 *unlink* - unlink the message queue
  32
  33 # CREATE USAGE
  34
  35 The *create* command accepts the following options:
  36
  37 -x, \--exclusive
  38 :   This causes queue creation to fail if the queue exists.
  39
  40 -m, \--mode MODE
  41 :   The MODE to open the file under, the actual mode of the queue
  42     will be AND-ed with the current umask (like open(2)).
  43
  44 -c, \--maxmsg COUNT
  45 :   The maximum messages in the queue.  The default and limit of this
  46     value is system-dependent.  This must be specified if \--msgsize is
  47     also specified.
  48
  49 -s, \--msgsize BYTES
  50 :   The maximum size of an individual message. The default and limit of
  51     this value is system-dependent.  This must be specified if \--maxmsg
  52     is also specified.
  53
  54 # ATTR USAGE
  55
  56 The *attr* command takes no special options nor command-line arguments.
  57 The output format of this command is suitable for "eval" in
  58 shell scripts.  Sample output is below:
  59
  60         flags=0
  61         maxmsg=10
  62         msgsize=8192
  63         curmsgs=3
  64
  65 See mq_getattr(3) for information on the meaning of the fields.
  66
  67 # SEND USAGE
  68
  69 The *send* command will read a message from standard input if no
  70 command-line arguments are given.  If command-line arguments are
  71 given, each argument is considered its own message and will be
  72 inserted into the queue separately.
  73
  74 The following command-line arguments are accepted:
  75
  76 -n, \--nonblock
  77 :   Exit immediately with error if the message queue is full.
  78     Normally posix-mq-rb(1) will block until the queue is writable or
  79     interrupted.  This may not be used in conjunction with \--timeout .
  80 -t, \--timeout SECONDS
  81 :   Timeout and exit with error after SECONDS if the message queue is full.
  82     This may not be used in conjunction with \--nonblock.
  83 -p, \--priority PRIORITY
  84 :   Specify an integer PRIORITY, this value should be 0 through 31
  85     (inclusive) for portability across POSIX-compliant systems.
  86     The default priority is 0.
  87
  88 # RECEIVE USAGE
  89
  90 The *receive* command will output message to standard output.  It will
  91 read a message from standard input if no command-line arguments are
  92 given.  If command-line arguments are given, each argument is considered
  93 its own message and will be inserted into the queue separately.
  94
  95 The following command-line arguments are accepted:
  96
  97 -n, \--nonblock
  98 :   Exit immediately with error if the message queue is empty.
  99     Normally posix-mq-rb(1) will block until the queue is readable or
 100     interrupted.  This may not be used in conjunction with \--timeout .
 101 -t, \--timeout SECONDS
 102 :   Timeout and exit with error after SECONDS if the message queue is empty.
 103     This may not be used in conjunction with \--nonblock.
 104 -p, \--priority
 105 :   Output the priority of the received message to stderr in the following
 106     format:
 107
 108         priority=3
 109
 110     The priority is an unsigned integer.
 111
 112 # WAIT USAGE
 113
 114 The *wait* command will cause posix-mq-rb(1) to sleep until a message is
 115 available in the queue.  Only one process may wait on an empty queue,
 116 posix-mq-rb(1) will exit with an error if there is another waiting process.
 117
 118 It takes no arguments and accepts the following options:
 119
 120 -t, \--timeout SECONDS
 121 :   Timeout and exit with error after SECONDS if the message queue is empty.
 122
 123 # UNLINK USAGE
 124
 125 The *unlink* command prevents further opening and use of the current
 126 queue.  Existing processes with the queue open may continue to operate
 127 on the queue indefinitely.  If a new queue is created with the same
 128 name, the created queue is a different queue from the unlinked queue.
 129 See mq_unlink(3) for more information.
 130
 131 # GENERAL OPTIONS
 132 -q
 133 :   Do not show warning/error messages, suitable for scripting.
 134
 135 \-h, \--help
 136 :   Show summary usage
 137
 138 # ENVIRONMENT
 139
 140 All commands rely on the MQUEUE environment variable.  The value
 141 of MQUEUE should always be prefixed with a slash ("/") for
 142 portability.
 143
 144 # DIAGNOSTICS
 145
 146 Exit status is normally 0.  Exit status is 2 if a timeout occurs, 1 for
 147 all other errors.
 148
 149 Under FreeBSD, the mq_* system calls are not available unless you load
 150 the mqueuefs(5) kernel module:
 151
 152         kldload mqueuefs
 153
 154 # SEE ALSO
 155
 156 * [mq_overview(7)][1]
 157 * [mqueuefs(5)][2]
 158
 159 [1]: http://kernel.org/doc/man-pages/online/pages/man7/mq_overview.7.html
 160 [2]: http://freebsd.org/cgi/man.cgi?query=mqueuefs