net-proto 1.0.6 → 1.1.0

data/CHANGES

@@ -1,3 +1,12 @@
+== 1.1.0 - 18-Jan-2012
+* Switched to FFI instead of C backend. Now works with JRuby, too.
+* Added the generic get_protocol instance method that accepts either a
+  string or an integer and does the right thing. This method should be
+  preferred going forward.
+* Documentation updates.
+* Refactored the test suite to use features of test-unit 2.x.
+* Added a default rake task.
+
 == 1.0.6 - 22-Oct-2010
 * Refactored the test suite and removed one test that was implementation
   dependent and not useful.

data/MANIFEST

@@ -2,12 +2,12 @@
 * MANIFEST
 * README
 * Rakefile
-* net-proto.gemspec
 * doc/netproto.txt
+* net-proto.gemspec
+* lib/net/proto.rb
+* lib/net/proto/common.rb
+* lib/generic/net/proto.rb
+* lib/linux/net/proto.rb
+* lib/sunos/net/proto.rb
 * examples/example_net_proto.rb
-* ext/version.h
-* ext/generic/generic.c
-* ext/linux/linux.c
-* ext/sunos/sunos.c 
-* ext/windows/windows.c
 * test/test_net_proto.rb

data/README

@@ -1,34 +1,41 @@
-= Description
+== Description
 The net-proto package provides a way to get protocol information.
 
-= Installation
+This is a wrapper for the getprotobyname(), getprotobynumber() and
+the getprotoent() functions.
+
+== Installation
 gem install net-proto
 
-= Synopsis
-require 'net/proto'
+== Prerequisites
+ffi 1.0.0 or later.
 
-Net::Proto.getprotobyname('tcp') # => 6
-Net::Proto.getprotobynumber(0)   # => 'ip'
+== Synopsis
+require 'net/proto'
 
-Net::Proto.getprotoent{ |entry| p entry }
+# Using generic method
+Net::Proto.get_protocol(1)      # => 'icmp'
+Net::Proto.get_protocol('icmp') # => 1
 
-= Notes
-This library is a wrapper for the getprotobyname(), getprotobynumber() and
-the getprotoent() functions.
+# Using type specific methods
+Net::Proto.getprotobynumber(6)   # => 'tcp'
+Net::Proto.getprotobyname('tcp') # => 6
 
-The net-proto package uses reentrant code for sunos and linux. Otherwise, the
-generic form of the functions are used (which may be reentrant by default
-anway - check the man pages on your platform).
+# Iterating over all protocols
+Net::Proto.getprotoent do |ent|
+  p ent
+end
 
+== MS Windows
 The Proto.getprotoent method is not supported on MS Windows because the
 underlying function isn't supported by the MS Windows API.
 
-= Why should I use this?
+== Why should I use this?
 Ruby has a predefined set of constants in socket.c in the general form of
 IPPROTO_XXX, Y.  However, using constants in this fashion can be unreliable
 because it's easy to define your own protocols (I set 'echo' to 7, for
 example), or to modify/delete entries in /etc/protocols.
 
-= Further Documentation
+== Further Documentation
 See the 'netproto.txt' file under the 'doc' directory for more details.  There
 is also an example under the 'examples' directory.

data/Rakefile

@@ -1,80 +1,29 @@
 require 'rake'
-require 'rake/clean'
 require 'rake/testtask'
-require 'rbconfig'
-include Config
-
-desc 'Clean the build files for the net-proto source' 
-task :clean do
-  Dir['*.gem'].each{ |f| File.delete(f) }
-  Dir['**/*.rbc'].each{ |f| File.delete(f) }
-
-  make = RUBY_PLATFORM.match('mswin') ? 'nmake' : 'make'
-
-  Dir.chdir('ext') do
-    proto_file = 'proto.' + Config::CONFIG['DLEXT']
-    if File.exists?('proto.o') || File.exists?(proto_file)
-      sh "#{make} distclean"
-    end
-    rm_rf('proto.c') if File.exists?('proto.c')
-    rm_rf('net') if File.exists?('net')
-  end
-
-  rm_rf('net') if File.exists?('net')
-  rm_rf('lib') if File.exists?('lib')
-end
+require 'rake/clean'
 
-desc 'Build the net-proto library'
-task :build => [:clean] do
-  make = RUBY_PLATFORM.match('mswin') ? 'nmake' : 'make'
-  Dir.chdir('ext') do
-    ruby 'extconf.rb'
-    sh make
-    build_file = 'proto.' + Config::CONFIG['DLEXT']
-    Dir.mkdir('net') unless File.exists?('net')
-    FileUtils.cp(build_file, 'net')
-  end
-end
+CLEAN.include('**/*.gem', '**/*.rbx', '**/*.rbc')
 
-namespace :gem do
-  desc 'Build a standard gem'
+namespace 'gem' do
+  desc 'Create the net-proto gem'
   task :create => :clean do
-    rm_rf('lib') if File.exists?('lib')
-    spec = eval(IO.read('net-proto.gemspec'))
-    Gem::Builder.new(spec).build
-  end
-
-  desc 'Build a binary gem'
-  task :create_binary => [:build] do
-    file = 'ext/net/proto.' + CONFIG['DLEXT']
-    mkdir_p('lib/net')
-    mv(file, 'lib/net')
-
     spec = eval(IO.read('net-proto.gemspec'))
-    spec.extensions = nil
-    spec.files = spec.files.reject{ |f| f.include?('ext/') }
-    spec.platform = Gem::Platform::CURRENT
-
     Gem::Builder.new(spec).build
   end
 
-  desc 'Install the net-proto library (gem)'
+  desc 'Install the net-proto gem'
   task :install => [:create] do
-    ruby 'net-proto.gemspec'
     file = Dir["net-proto*.gem"].last
     sh "gem install #{file}"
   end
 end
 
 desc 'Run the example net-proto program'
-task :example => [:build] do
-  Dir.mkdir('net') unless File.exists?('net')
-  ruby '-Iext examples/example_net_proto.rb'
+task :example do
+  ruby '-Ilib examples/example_net_proto.rb'
 end
 
 Rake::TestTask.new do |t|
-  task :test => :build
-  t.libs << 'ext'
   t.warning = true
   t.verbose = true
 end

data/doc/netproto.txt

@@ -44,39 +44,36 @@ Proto.getprotoent{ |struct| ... }
     
 == Notes
    This module uses the reentrant (i.e. thread safe) functions on those
-   platforms that support them.  In some cases, e.g. FreeBSD and HP-UX, the
+   platforms that support them. In some cases, e.g. FreeBSD and HP-UX, the
    standard function names are reentrant by default (i.e. there is no '_r'
-   version, or it's not needed), so you will not see specific .c files for
-   all platforms.
+   version, or it's not needed).
 
    The 'setprotoent()' and 'endprotoent()' functions are not implemented as
-   separate method calls.  Rather, these are called internally by the various
+   separate method calls. Rather, these are called internally by the various
    methods, except on Windows, which does not support them.
 
    The 'getprotoent()' method is not supported on the MS Windows platform.
    It's not part of the API as of Windows XP.
    
 == Known Bugs
-   None that I'm aware of.  Please log any bug reports on the project page
-   at http://ruby-netutils.sf.net.
+  None that I'm aware of.  Please log any bug reports on the project page
+  at https://github.com/djberg96/net-proto.
 	
 == Future Plans
-   Use the asynchronous calls (WSAAsyncGetProtoByName and
-   WSAAsyncGetProtoByNumber) on MS Windows systems.
+  Use the asynchronous calls (WSAAsyncGetProtoByName and
+  WSAAsyncGetProtoByNumber) on MS Windows systems.
 	
 == Copyright
-   (C) 2003-2007 Daniel J. Berger
-   All rights reserved.
+  (C) 2003-2012 Daniel J. Berger
+  All rights reserved.
 	
 == Warranty
-   This package is provided "as is" and without any express or
-   implied warranties, including, without limitation, the implied
-   warranties of merchantability and fitness for a particular purpose.
+  This package is provided "as is" and without any express or
+  implied warranties, including, without limitation, the implied
+  warranties of merchantability and fitness for a particular purpose.
 	
 == License
-   Ruby's
+  Artistic 2.0
 	
 == Author
-   Daniel J. Berger
-   djberg96 at gmail dot com
-   imperator on IRC (Freenode)
+  Daniel J. Berger

data/examples/example_net_proto.rb

@@ -4,7 +4,7 @@
 # A generic test program for general futzing. You cna run this example
 # code via the 'rake example' task.
 #########################################################################
-require 'net/proto''
+require 'net/proto'
 include Net
 
 puts "VERSION: " + Proto::VERSION
@@ -12,14 +12,14 @@ puts "VERSION: " + Proto::VERSION
 puts "UDP port: " + Proto.getprotobyname("udp").to_s
 
 unless File::ALT_SEPARATOR
-   puts "Name\t\tProto\tAliases"
-   puts "=========================="
+  puts "Name\t\tProto\tAliases"
+  puts "=========================="
 
-   Proto.getprotoent.each{ |s|
-      if s.name.length > 7
-         puts s.name + "\t" + s.proto.to_s + "\t" + s.aliases.join(", ")
-      else
-         puts s.name + "\t\t" + s.proto.to_s + "\t" + s.aliases.join(", ")
-      end
-}
-end
+  Proto.getprotoent.each{ |s|
+    if s.name.length > 7
+      puts s.name + "\t" + s.proto.to_s + "\t" + s.aliases.join(", ")
+    else
+      puts s.name + "\t\t" + s.proto.to_s + "\t" + s.aliases.join(", ")
+    end
+  }
+end

data/lib/generic/net/proto.rb

@@ -0,0 +1,145 @@
+require 'net/proto/common'
+
+# The Net module serves as a namespace only.
+module Net
+  # The Proto class serves as the base class for the various protocol methods.
+  class Proto
+    extend FFI::Library
+
+    ffi_lib FFI::Library::LIBC
+
+    if File::ALT_SEPARATOR
+      ffi_lib 'ws2_32'
+      ffi_convention :stdcall
+    end
+
+    private
+
+    # These should exist on every platform.
+    attach_function :getprotobyname_c, :getprotobyname, [:string], :pointer
+    attach_function :getprotobynumber_c, :getprotobynumber, [:int], :pointer
+
+    # These are defined on most platforms, but not all.
+    begin
+      attach_function :setprotoent, [:int], :void
+      attach_function :endprotoent, [], :void
+      attach_function :getprotoent_c, :getprotoent, [], :pointer
+    rescue FFI::NotFoundError
+      # Ignore, not supported. Probably Windows.
+    else
+      private_class_method :setprotoent
+      private_class_method :endprotoent
+      private_class_method :getprotoent_c
+    end
+
+    private_class_method :getprotobyname_c
+    private_class_method :getprotobynumber_c
+
+    public
+
+    # If given a protocol string, returns the corresponding number. If
+    # given a protocol number, returns the corresponding string.
+    #
+    # Returns nil if not found in either case.
+    #
+    # Examples:
+    #
+    #   Net::Proto.get_protocol('tcp') # => 6
+    #   Net::Proto.get_protocol(1)     # => 'icmp'
+    #
+    def self.get_protocol(arg)
+      if arg.is_a?(String)
+        getprotobyname(arg)
+      else
+        getprotobynumber(arg)
+      end
+    end
+
+    # Given a protocol string, returns the corresponding number, or nil if
+    # not found.
+    #
+    # Examples:
+    #
+    #    Net::Proto.getprotobyname('tcp')   # => 6
+    #    Net::Proto.getprotobyname('bogus') # => nil
+    #
+    def self.getprotobyname(protocol)
+      raise TypeError unless protocol.is_a?(String)
+
+      begin
+        setprotoent(0) if respond_to?(:setprotoent, true)
+        ptr = getprotobyname_c(protocol)
+        struct = ProtocolStruct.new(ptr) unless ptr.null?
+      ensure
+        endprotoent() if respond_to?(:endprotoent, true)
+      end
+
+      ptr.null? ? nil : struct[:p_proto]
+    end
+
+    # Given a protocol number, returns the corresponding string, or nil if
+    # not found.
+    #
+    # Examples:
+    #
+    #   Net::Proto.getprotobynumber(6)   # => 'tcp'
+    #   Net::Proto.getprotobynumber(999) # => nil
+    #
+    def self.getprotobynumber(protocol)
+      raise TypeError unless protocol.is_a?(Integer)
+
+      begin
+        setprotoent(0) if respond_to?(:setprotoent, true)
+        ptr = getprotobynumber_c(protocol)
+        struct = ProtocolStruct.new(ptr) unless ptr.null?
+      ensure
+        endprotoent() if respond_to?(:endprotoent, true)
+      end
+
+      ptr.null? ? nil: struct[:p_name]
+    end
+
+    # In block form, yields each entry from /etc/protocols as a struct of type
+    # Proto::ProtoStruct. In non-block form, returns an array of structs.
+    #
+    # The fields are 'name' (a string), 'aliases' (an array of strings,
+    # though often only one element), and 'proto' (a number).
+    #
+    # Example:
+    #
+    #   Net::Proto.getprotoent.each{ |prot|
+    #      p prot.name
+    #      p prot.aliases
+    #      p prot.proto
+    #   }
+    #
+    def self.getprotoent
+      raise NoMethodError unless respond_to?(:getprotoent, true)
+
+      structs = block_given? ? nil : []
+
+      begin
+        setprotoent(0)
+        until (ptr = getprotoent_c()).null?
+          ffi_struct  = ProtocolStruct.new(ptr)
+
+          ruby_struct = ProtoStruct.new(
+            ffi_struct[:p_name],
+            ffi_struct[:p_aliases].read_array_of_string,
+            ffi_struct[:p_proto]
+          ).freeze
+
+          if block_given?
+            yield ruby_struct
+          else
+            structs << ruby_struct
+          end
+        end
+      ensure
+        endprotoent()
+      end
+
+      structs
+    end
+  end
+end

data/lib/linux/net/proto.rb

@@ -0,0 +1,140 @@
+require 'net/proto/common'
+
+# The Net module serves as a namespace only.
+module Net
+
+  # The Proto class serves as the base class for the various protocol methods.
+  class Proto
+    ffi_lib FFI::Library::LIBC
+
+    private
+
+    attach_function :setprotoent, [:int], :void
+    attach_function :endprotoent, [], :void
+    attach_function :getprotobyname_r, [:string, :pointer, :pointer, :long, :pointer], :int
+    attach_function :getprotobynumber_r, [:int, :pointer, :pointer, :long, :pointer], :int
+    attach_function :getprotoent_r, [:pointer, :pointer, :long, :pointer], :int
+
+    private_class_method :setprotoent, :endprotoent, :getprotobyname_r
+    private_class_method :getprotobynumber_r, :getprotoent_r
+
+    public
+
+    # If given a protocol string, returns the corresponding number. If
+    # given a protocol number, returns the corresponding string.
+    #
+    # Returns nil if not found in either case.
+    #
+    # Examples:
+    #
+    #   Net::Proto.get_protocol('tcp') # => 6
+    #   Net::Proto.get_protocol(1)     # => 'icmp'
+    #
+    def self.get_protocol(argument)
+      if argument.is_a?(String)
+        getprotobyname(argument)
+      else
+        getprotobynumber(argument)
+      end
+    end
+
+    # Given a protocol string, returns the corresponding number, or nil if
+    # not found.
+    #
+    # Examples:
+    #
+    #    Net::Proto.getprotobyname('tcp')   # => 6
+    #    Net::Proto.getprotobyname('bogus') # => nil
+    #
+    def self.getprotobyname(protocol)
+      raise TypeError unless protocol.is_a?(String)
+
+      pptr = FFI::MemoryPointer.new(ProtocolStruct.size)
+      qptr = FFI::MemoryPointer.new(ProtocolStruct.size)
+      buf  = FFI::MemoryPointer.new(:char, 1024)
+
+      begin
+        setprotoent(0)
+        int = getprotobyname_r(protocol, pptr, buf, buf.size, qptr)
+      ensure
+        endprotoent()
+      end
+
+      int > 0 || qptr.get_pointer(0).null? ? nil : ProtocolStruct.new(pptr)[:p_proto]
+    end
+
+    # Given a protocol number, returns the corresponding string, or nil if
+    # not found.
+    #
+    # Examples:
+    #
+    #   Net::Proto.getprotobynumber(6)   # => 'tcp'
+    #   Net::Proto.getprotobynumber(999) # => nil
+    #
+    def self.getprotobynumber(protocol)
+      raise TypeError unless protocol.is_a?(Integer)
+
+      pptr = FFI::MemoryPointer.new(ProtocolStruct.size)
+      qptr = FFI::MemoryPointer.new(ProtocolStruct.size)
+      buf  = FFI::MemoryPointer.new(:char, 1024)
+
+      begin
+        setprotoent(0)
+        int = getprotobynumber_r(protocol, pptr, buf, buf.size, qptr)
+      ensure
+        endprotoent()
+      end
+
+      int > 0 || qptr.get_pointer(0).null? ? nil : ProtocolStruct.new(pptr)[:p_name]
+    end
+
+    # In block form, yields each entry from /etc/protocols as a struct of type
+    # Proto::ProtoStruct. In non-block form, returns an array of structs.
+    #
+    # The fields are 'name' (a string), 'aliases' (an array of strings,
+    # though often only one element), and 'proto' (a number).
+    #
+    # Example:
+    #
+    #   Net::Proto.getprotoent.each{ |prot|
+    #      p prot.name
+    #      p prot.aliases
+    #      p prot.proto
+    #   }
+    #
+    def self.getprotoent
+      structs = block_given? ? nil : []
+
+      pptr = FFI::MemoryPointer.new(ProtocolStruct.size)
+      qptr = FFI::MemoryPointer.new(ProtocolStruct.size)
+      buf  = FFI::MemoryPointer.new(1024)
+
+      begin
+        setprotoent(0)
+
+        while int = getprotoent_r(pptr, buf, buf.size, qptr)
+          break if int > 0 || qptr.null?
+          buf = FFI::MemoryPointer.new(1024)
+
+          ffi_struct = ProtocolStruct.new(pptr)
+
+          ruby_struct = ProtoStruct.new(
+            ffi_struct[:p_name],
+            ffi_struct[:p_aliases].read_array_of_string,
+            ffi_struct[:p_proto]
+          ).freeze
+
+          if block_given?
+            yield ruby_struct
+          else
+            structs << ruby_struct
+          end
+        end
+      ensure
+        endprotoent
+      end
+
+      structs
+    end
+  end
+end