From 7b1b8a1cbbedc2764d4a8ab0d992f9f2ef73d9b7 Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Tue, 4 May 2010 19:31:47 -0700 Subject: rename `posix-mq.rb' executable to `posix-mq-rb' ".rb" in the executable name is discouraged by the {Ruby packaging standard}[http://github.com/chneukirchen/rps] and probably confusing. If I ever get around to it, a non-Ruby version of this executable is planned, and that will be called "posix-mq" --- .document | 2 +- Documentation/GNUmakefile | 2 +- Documentation/posix-mq-rb.1.txt | 160 ++++++++++++++++++++++++++++++++++++++++ Documentation/posix-mq.rb.1.txt | 160 ---------------------------------------- GNUmakefile | 2 +- README | 2 +- bin/posix-mq-rb | 138 ++++++++++++++++++++++++++++++++++ bin/posix-mq.rb | 138 ---------------------------------- posix_mq.gemspec | 2 +- 9 files changed, 303 insertions(+), 303 deletions(-) create mode 100644 Documentation/posix-mq-rb.1.txt delete mode 100644 Documentation/posix-mq.rb.1.txt create mode 100755 bin/posix-mq-rb delete mode 100755 bin/posix-mq.rb diff --git a/.document b/.document index 6f5c676..37db68c 100644 --- a/.document +++ b/.document @@ -4,4 +4,4 @@ NEWS ChangeLog lib ext/posix_mq/posix_mq.c -posix-mq.rb.1 +posix-mq-rb.1 diff --git a/Documentation/GNUmakefile b/Documentation/GNUmakefile index 8aea6ae..5a68884 100644 --- a/Documentation/GNUmakefile +++ b/Documentation/GNUmakefile @@ -5,7 +5,7 @@ PANDOC_OPTS = -f markdown --email-obfuscation=none --sanitize-html pandoc = $(PANDOC) $(PANDOC_OPTS) pandoc_html = $(pandoc) --toc -t html --no-wrap -man1 := $(addsuffix .1,posix-mq.rb) +man1 := $(addsuffix .1,posix-mq-rb) html1 := $(addsuffix .html,$(man1)) all:: html man diff --git a/Documentation/posix-mq-rb.1.txt b/Documentation/posix-mq-rb.1.txt new file mode 100644 index 0000000..2972a96 --- /dev/null +++ b/Documentation/posix-mq-rb.1.txt @@ -0,0 +1,160 @@ +% posix-mq-rb(1) posix-mq-rb User Manual +% Ruby POSIX MQ hackers +% Jan 1, 2010 + +# NAME + +posix-mq-rb - command-line interface for POSIX message queues + +# SYNOPSIS + +MQUEUE=/name posix-mq-rb COMMAND [*OPTIONS*] [*ARGUMENTS*] + +# DESCRIPTION + +A command-line interface for manipulating POSIX message queues. It is +useful for testing and debugging applications using POSIX message +queues. + +# COMMANDS + +*create* - create a new message queue + +*attr* - output attributes of the message queue + +*send* - insert a message into the queue from stdin or the command-line + +*receive* - take a message from the queue and outputs it to stdout + +*wait* - sleep until a message is available in the queue + +*unlink* - unlink the message queue + +# CREATE USAGE + +The *create* command accepts the following options: + +-x, \--exclusive +: This causes queue creation to fail if the queue exists. + +-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)). + +-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. + +-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. + +# ATTR USAGE + +The *attr* 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: + + flags=0 + maxmsg=10 + msgsize=8192 + curmsgs=3 + +See mq_getattr(3) for information on the meaning of the fields. + +# SEND USAGE + +The *send* 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. + +The following command-line arguments are accepted: + +-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 . +-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. +-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. + +# RECEIVE USAGE + +The *receive* 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. + +The following command-line arguments are accepted: + +-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 . +-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. +-p, \--priority +: Output the priority of the received message to stderr in the following + format: + + priority=3 + + The priority is an unsigned integer. + +# WAIT USAGE + +The *wait* 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. + +It takes no arguments and accepts the following options: + +-t, \--timeout SECONDS +: Timeout and exit with error after SECONDS if the message queue is empty. + +# UNLINK USAGE + +The *unlink* 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. + +# GENERAL OPTIONS +-q +: Do not show warning/error messages, suitable for scripting. + +\-h, \--help +: Show summary usage + +# ENVIRONMENT + +All commands rely on the MQUEUE environment variable. The value +of MQUEUE should always be prefixed with a slash ("/") for +portability. + +# DIAGNOSTICS + +Exit status is normally 0. Exit status is 2 if a timeout occurs, 1 for +all other errors. + +Under FreeBSD, the mq_* system calls are not available unless you load +the mqueuefs(5) kernel module: + + kldload mqueuefs + +# SEE ALSO + +* [mq_overview(7)][1] +* [mqueuefs(5)][2] + +[1]: http://kernel.org/doc/man-pages/online/pages/man7/mq_overview.7.html +[2]: http://freebsd.org/cgi/man.cgi?query=mqueuefs diff --git a/Documentation/posix-mq.rb.1.txt b/Documentation/posix-mq.rb.1.txt deleted file mode 100644 index 0cf0bc3..0000000 --- a/Documentation/posix-mq.rb.1.txt +++ /dev/null @@ -1,160 +0,0 @@ -% posix-mq.rb(1) posix-mq.rb User Manual -% Ruby POSIX MQ hackers -% Jan 1, 2010 - -# NAME - -posix-mq.rb - command-line interface for POSIX message queues - -# SYNOPSIS - -MQUEUE=/name posix-mq.rb COMMAND [*OPTIONS*] [*ARGUMENTS*] - -# DESCRIPTION - -A command-line interface for manipulating POSIX message queues. It is -useful for testing and debugging applications using POSIX message -queues. - -# COMMANDS - -*create* - create a new message queue - -*attr* - output attributes of the message queue - -*send* - insert a message into the queue from stdin or the command-line - -*receive* - take a message from the queue and outputs it to stdout - -*wait* - sleep until a message is available in the queue - -*unlink* - unlink the message queue - -# CREATE USAGE - -The *create* command accepts the following options: - --x, \--exclusive -: This causes queue creation to fail if the queue exists. - --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)). - --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. - --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. - -# ATTR USAGE - -The *attr* 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: - - flags=0 - maxmsg=10 - msgsize=8192 - curmsgs=3 - -See mq_getattr(3) for information on the meaning of the fields. - -# SEND USAGE - -The *send* 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. - -The following command-line arguments are accepted: - --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 . --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. --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. - -# RECEIVE USAGE - -The *receive* 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. - -The following command-line arguments are accepted: - --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 . --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. --p, \--priority -: Output the priority of the received message to stderr in the following - format: - - priority=3 - - The priority is an unsigned integer. - -# WAIT USAGE - -The *wait* 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. - -It takes no arguments and accepts the following options: - --t, \--timeout SECONDS -: Timeout and exit with error after SECONDS if the message queue is empty. - -# UNLINK USAGE - -The *unlink* 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. - -# GENERAL OPTIONS --q -: Do not show warning/error messages, suitable for scripting. - -\-h, \--help -: Show summary usage - -# ENVIRONMENT - -All commands rely on the MQUEUE environment variable. The value -of MQUEUE should always be prefixed with a slash ("/") for -portability. - -# DIAGNOSTICS - -Exit status is normally 0. Exit status is 2 if a timeout occurs, 1 for -all other errors. - -Under FreeBSD, the mq_* system calls are not available unless you load -the mqueuefs(5) kernel module: - - kldload mqueuefs - -# SEE ALSO - -* [mq_overview(7)][1] -* [mqueuefs(5)][2] - -[1]: http://kernel.org/doc/man-pages/online/pages/man7/mq_overview.7.html -[2]: http://freebsd.org/cgi/man.cgi?query=mqueuefs diff --git a/GNUmakefile b/GNUmakefile index 10e81e9..cd485a0 100644 --- a/GNUmakefile +++ b/GNUmakefile @@ -15,7 +15,7 @@ ifeq ($(RUBY_VERSION),) RUBY_VERSION := $(shell $(RUBY) -e 'puts RUBY_VERSION') endif -base_bins := posix-mq.rb +base_bins := posix-mq-rb bins := $(addprefix bin/, $(base_bins)) man1_bins := $(addsuffix .1, $(base_bins)) man1_paths := $(addprefix man/man1/, $(man1_bins)) diff --git a/README b/README index 03d9f50..170e01f 100644 --- a/README +++ b/README @@ -28,7 +28,7 @@ network-aware message queue implementations. * Documented library API -* Includes a generic "posix-mq.rb" command-line tool with manpage. +* Includes a generic "posix-mq-rb" command-line tool with manpage. == Install diff --git a/bin/posix-mq-rb b/bin/posix-mq-rb new file mode 100755 index 0000000..aab0b61 --- /dev/null +++ b/bin/posix-mq-rb @@ -0,0 +1,138 @@ +#!/usr/bin/env ruby +# -*- encoding: binary -*- +Encoding.default_external = Encoding::BINARY if defined?(Encoding) +$stderr.sync = $stdout.sync = true + +require 'posix_mq' +require 'optparse' + +commands = %w(create attr send receive wait unlink) +usage = "Usage: MQUEUE=/name #{File.basename($0)} COMMAND " \ + "[options] []\n" \ + "COMMAND may be one of: #{commands.join(', ')}" + +mqueue = ENV["MQUEUE"] or abort usage +command = ARGV.shift or abort usage +commands.include?(command) or abort usage + +priority = nil +timeout = nil +mode = 0666 +oflags = IO::RDONLY +mq_attr = nil +nonblock = false +command = command.to_sym + +ARGV.options do |x| + x.banner = usage.split(/\n/).first.gsub(/COMMAND/, command.to_s) + x.separator '' + + case command + when :create + oflags |= IO::CREAT + x.on('-x', '--exclusive', "exclusive create") { + oflags |= IO::EXCL + } + x.on('-m', '--mode=MODE', "octal file mode") { |i| + mode = i.to_i(8) + } + x.on('-c', '--maxmsg=COUNT', Integer, "maximum number of messages") { |i| + mq_attr ||= POSIX_MQ::Attr.new + mq_attr.maxmsg = i + } + x.on('-s', '--msgsize=BYTES', Integer, "maximum size of message") { |i| + mq_attr ||= POSIX_MQ::Attr.new + mq_attr.msgsize = i + } + when :wait + x.on('-t', '--timeout=SECONDS', Float, "timeout in seconds") { |f| + timeout = f + } + when :send, :receive + conflict = "timeout and nonblock are exclusive" + x.on('-t', '--timeout=SECONDS', Float, "timeout in seconds") { |f| + abort conflict if nonblock + timeout = f + } + x.on('-n', '--nonblock', "nonblocking operation") { + abort conflict if timeout + nonblock = true + oflags |= IO::NONBLOCK + } + if command == :send + oflags = IO::WRONLY + x.on('-p', '--priority=PRIO', Integer, "priority of message") { |i| + priority = i + } + else + x.on('-p', '--priority', "output priority of message to stderr") { + priority = $stderr + } + end + end + x.on('-q', "quiet warnings and errors") { $stderr.reopen("/dev/null", "w") } + x.on('-h', '--help', 'Show this help message.') { puts x; exit } + x.parse! +end + +trap(:INT) { exit 130 } + +unless command == :send || ARGV.empty? + abort "#{command} accepts no arguments" +end + +begin + if command == :create && mq_attr + mq_attr.flags = mq_attr.curmsgs = 0 + mq_attr.msgsize && ! mq_attr.maxmsg and + abort "--maxmsg must be set with --msgsize" + mq_attr.maxmsg && ! mq_attr.msgsize and + abort "--msgsize must be set with --maxmsg" + elsif command == :unlink + POSIX_MQ.unlink(mqueue) + exit + end + + mq = POSIX_MQ.open(mqueue, oflags, mode, mq_attr) + case command + when :create + exit + when :receive + buf, prio = mq.receive("", timeout) + $stderr.syswrite("priority=#{prio}\n") if priority + $stdout.syswrite(buf) + when :send + ARGV << $stdin.read if ARGV.empty? + ARGV.each { |msg| mq.send(msg, priority, timeout) } + when :attr + mq_attr = mq.attr + $stdout.syswrite( + "flags=#{mq_attr.flags}\n" \ + "maxmsg=#{mq_attr.maxmsg}\n" \ + "msgsize=#{mq_attr.msgsize}\n" \ + "curmsgs=#{mq_attr.curmsgs}\n") + when :wait + trap(:USR1) { exit } + + # we wouldn't get a notification if there were already messages + exit if mq.attr.curmsgs > 0 + mq.notify = :USR1 + exit if mq.attr.curmsgs > 0 # avoid race condition + + timeout.nil? ? sleep : sleep(timeout) + exit 2 # timed out + end +rescue Errno::EEXIST + abort "Queue exists" +rescue Errno::ENOENT + abort "Queue does not exist" +rescue Errno::EMSGSIZE + abort "Message too long" +rescue Errno::EAGAIN + abort(command == :send ? "Queue full" : "No messages available") +rescue Errno::ETIMEDOUT + warn "Operation timed out" + exit 2 +rescue => e + abort e.message +end diff --git a/bin/posix-mq.rb b/bin/posix-mq.rb deleted file mode 100755 index fa44b94..0000000 --- a/bin/posix-mq.rb +++ /dev/null @@ -1,138 +0,0 @@ -#!/usr/bin/ruby -# -*- encoding: binary -*- -Encoding.default_external = Encoding::BINARY if defined?(Encoding) -$stderr.sync = $stdout.sync = true - -require 'posix_mq' -require 'optparse' - -commands = %w(create attr send receive wait unlink) -usage = "Usage: MQUEUE=/name #{File.basename($0)} COMMAND " \ - "[options] []\n" \ - "COMMAND may be one of: #{commands.join(', ')}" - -mqueue = ENV["MQUEUE"] or abort usage -command = ARGV.shift or abort usage -commands.include?(command) or abort usage - -priority = nil -timeout = nil -mode = 0666 -oflags = IO::RDONLY -mq_attr = nil -nonblock = false -command = command.to_sym - -ARGV.options do |x| - x.banner = usage.split(/\n/).first.gsub(/COMMAND/, command.to_s) - x.separator '' - - case command - when :create - oflags |= IO::CREAT - x.on('-x', '--exclusive', "exclusive create") { - oflags |= IO::EXCL - } - x.on('-m', '--mode=MODE', "octal file mode") { |i| - mode = i.to_i(8) - } - x.on('-c', '--maxmsg=COUNT', Integer, "maximum number of messages") { |i| - mq_attr ||= POSIX_MQ::Attr.new - mq_attr.maxmsg = i - } - x.on('-s', '--msgsize=BYTES', Integer, "maximum size of message") { |i| - mq_attr ||= POSIX_MQ::Attr.new - mq_attr.msgsize = i - } - when :wait - x.on('-t', '--timeout=SECONDS', Float, "timeout in seconds") { |f| - timeout = f - } - when :send, :receive - conflict = "timeout and nonblock are exclusive" - x.on('-t', '--timeout=SECONDS', Float, "timeout in seconds") { |f| - abort conflict if nonblock - timeout = f - } - x.on('-n', '--nonblock', "nonblocking operation") { - abort conflict if timeout - nonblock = true - oflags |= IO::NONBLOCK - } - if command == :send - oflags = IO::WRONLY - x.on('-p', '--priority=PRIO', Integer, "priority of message") { |i| - priority = i - } - else - x.on('-p', '--priority', "output priority of message to stderr") { - priority = $stderr - } - end - end - x.on('-q', "quiet warnings and errors") { $stderr.reopen("/dev/null", "w") } - x.on('-h', '--help', 'Show this help message.') { puts x; exit } - x.parse! -end - -trap(:INT) { exit 130 } - -unless command == :send || ARGV.empty? - abort "#{command} accepts no arguments" -end - -begin - if command == :create && mq_attr - mq_attr.flags = mq_attr.curmsgs = 0 - mq_attr.msgsize && ! mq_attr.maxmsg and - abort "--maxmsg must be set with --msgsize" - mq_attr.maxmsg && ! mq_attr.msgsize and - abort "--msgsize must be set with --maxmsg" - elsif command == :unlink - POSIX_MQ.unlink(mqueue) - exit - end - - mq = POSIX_MQ.open(mqueue, oflags, mode, mq_attr) - case command - when :create - exit - when :receive - buf, prio = mq.receive("", timeout) - $stderr.syswrite("priority=#{prio}\n") if priority - $stdout.syswrite(buf) - when :send - ARGV << $stdin.read if ARGV.empty? - ARGV.each { |msg| mq.send(msg, priority, timeout) } - when :attr - mq_attr = mq.attr - $stdout.syswrite( - "flags=#{mq_attr.flags}\n" \ - "maxmsg=#{mq_attr.maxmsg}\n" \ - "msgsize=#{mq_attr.msgsize}\n" \ - "curmsgs=#{mq_attr.curmsgs}\n") - when :wait - trap(:USR1) { exit } - - # we wouldn't get a notification if there were already messages - exit if mq.attr.curmsgs > 0 - mq.notify = :USR1 - exit if mq.attr.curmsgs > 0 # avoid race condition - - timeout.nil? ? sleep : sleep(timeout) - exit 2 # timed out - end -rescue Errno::EEXIST - abort "Queue exists" -rescue Errno::ENOENT - abort "Queue does not exist" -rescue Errno::EMSGSIZE - abort "Message too long" -rescue Errno::EAGAIN - abort(command == :send ? "Queue full" : "No messages available") -rescue Errno::ETIMEDOUT - warn "Operation timed out" - exit 2 -rescue => e - abort e.message -end diff --git a/posix_mq.gemspec b/posix_mq.gemspec index 73c0a53..d4cf30e 100644 --- a/posix_mq.gemspec +++ b/posix_mq.gemspec @@ -12,7 +12,7 @@ Gem::Specification.new do |s| s.date = Time.now.utc.strftime('%Y-%m-%d') s.description = File.read("README").split(/\n\n/)[1] s.email = %q{ruby.posix.mq@librelist.com} - s.executables = %w(posix-mq.rb) + s.executables = %w(posix-mq-rb) s.extensions = %w(ext/posix_mq/extconf.rb) s.extra_rdoc_files = File.readlines('.document').map! do |x| -- cgit v1.2.3-24-ge0c7