From e7ac70686b3c09953f6c41966dbd77f77368a9ec Mon Sep 17 00:00:00 2001
From: Eric Wong <normalperson@yhbt.net>
Date: Sat, 2 Jan 2010 21:19:58 -0800
Subject: doc: FreeBSD-specific notes + example code

---
 Documentation/posix-mq.rb.1.txt |  7 +++++++
 README                          | 36 ++++++++++++++++++++++++++++++++++++
 2 files changed, 43 insertions(+)

diff --git a/Documentation/posix-mq.rb.1.txt b/Documentation/posix-mq.rb.1.txt
index e9005ee..0cf0bc3 100644
--- a/Documentation/posix-mq.rb.1.txt
+++ b/Documentation/posix-mq.rb.1.txt
@@ -146,8 +146,15 @@ portability.
 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/README b/README
index 91279db..64b6832 100644
--- a/README
+++ b/README
@@ -42,6 +42,42 @@ Unpack it, and run "ruby setup.rb"
 
 Otherwise, via RubyGems: gem install posix_mq
 
+== Usage
+
+The Linux mq_overview(7)
+{manpage}[http://kernel.org/doc/man-pages/online/pages/man7/mq_overview.7.html]
+provides a good overview of programming with POSIX message queues.
+
+Under FreeBSD, you must load the
+{mqueuefs(5)}[http://freebsd.org/cgi/man.cgi?query=mqueuefs]
+kernel module before attempting to use POSIX message queues:
+
+    kldload mqueuefs
+
+Our API matches the C api closely, see the RDoc for full API
+documentation.  Here is an example of a process communicating
+with itself.  In practice, processes that send will be different
+from processes that receive.
+
+    require 'posix_mq'
+    mq = POSIX_MQ.new("/foo", :rw)
+
+    # hello world
+    mq << "hello world"
+    puts mq.receive.first # => should print "hello world"
+
+    # non-blocking operation
+    mq.nonblock = true
+    begin
+      mq.receive
+    rescue Errno::EAGAIN
+    end
+
+    trap(:USR1) { puts mq.receive.first }
+    mq.notify = :USR1
+    mq.send "fire USR1 handler"
+    # "fire USR1 handler" should be printed now
+
 == Development
 
 You can get the latest source via git from the following locations:
-- 
cgit v1.2.3-24-ge0c7