win32-process 0.6.6 → 0.7.0

data/CHANGES

@@ -1,8 +1,13 @@
-= 0.6.6 - 19-Jul-2012
-* Fixed a param bug in the Process.fork method caused by a prototype change
-  in the Windows::Process library of the windows-pr gem. Thanks go to
-  mzverev for the spot.
-* Updated the gemspec, including updates to the windows-pr dependency.
+= 0.7.0 - 22-Aug-2012
+* Converted to use FFI instead of win32-api.
+* Now requires Ruby 1.9.x or later.
+* Removed the experimental Process.fork function. This obviated the necessity
+  of custom implementations of other methods, like Process.waitpid, so those
+  no longer have custom implementations either. These also proved to be
+  somewhat problematic with Ruby 1.9.x anyway.
+* Removed the custom Process.ppid method because Ruby 1.9.x now supports it.
+* The Process.kill method now supports the :exit_proc, :dll_module and
+  :wait_time options for signals 1 and 4-8.
 
 = 0.6.5 - 27-Dec-2010
 * Fixed getpriority and setpriority so that the underlying process handle is

data/MANIFEST

@@ -1,11 +1,9 @@
-* CHANGES
-* README
-* MANIFEST
-* Rakefile
-* win32-process.gemspec
-* examples/example_create.rb
-* examples/example_fork_wait.rb
-* examples/example_fork_waitpid.rb
-* examples/example_kill.rb
-* lib/win32/process.rb
-* test/test_process.rb
+* CHANGES
+* README
+* MANIFEST
+* Rakefile
+* win32-process.gemspec
+* examples/example_create.rb
+* examples/example_kill.rb
+* lib/win32/process.rb
+* test/test_process.rb

data/README

@@ -1,12 +1,10 @@
 = Description
-  This library provides the fork, wait, wait2, waitpid, and waitpid2 methods
-  for MS Windows. In addition, it provides a different implementation of the
-  kill method, a proper implementation of Process.ppid, and decent analogues
-  of Process.getpriority, Process.setpriority, Process.getrlimit and
-  Process.setrlimit.
-
+  This library provides analogues of the :getpriority, :setpriority, :getrlimit,
+  :setrlimit and :uid methods for MS Windows. It also adds the new methods :job?,
+  :get_affinity, and :create, and redefines the :kill method.
+ 
 = Prerequisites
-  * windows-pr
+  * ffi
   * sys-proctable (dev only)
   * test-unit 2 (dev only)
 
@@ -19,92 +17,53 @@
 = Synopsis
   require 'win32/process'
 
-  Process.fork{
-    3.times{
-      puts 'In the child'
-      sleep 1
-    }
-  }
+  p Process.job? # => true or false
 
-  Process.wait
-  puts 'Done'
-	
-= Developer's Notes
-== The Process.fork and Process.wait methods
-   The fork method is emulated on Windows by spawning another Ruby process
-   against $PROGRAM_NAME via the CreateProcess() Win32 API function. It will
-   use its parent's environment and starting directory.
-	
-   The various wait methods are a wrapper for the WaitForSingleObject() or
-   WaitForMultipleObjects() Win32 API functions, for the wait* and waitpid*
-   methods, respectively.  In the case of wait2 and waitpid2, the exit value
-   is returned via the GetExitCodeProcess() Win32API function.
-	
-   For now the waitpid and waitpid2 calls do not accept a second argument.
-   That's because we haven't yet determined if there's a signal we should
-   allow to be sent.
+  info = Process.create(
+    :app_name         => "notepad.exe",
+    :creation_flags   => Process::DETACHED_PROCESS,
+    :process_inherit  => false,
+    :thread_inherit   => true,
+    :cwd              => "C:\\"
+  )
 
-   IMPORTANT!	
-   Note that because fork is calling CreateProcess($PROGRAM_NAME), it will
-   start again from the top of the script instead of from the point of the
-   call. We will try to address this in a future release, if possible.
+  p info.process_id
 	
-== The Process.kill method
-   Initially, the kill method will try to get a HANDLE on the PID using the
-   OpenProcess() function. If that succeeds, we know the process is running.
-
-   In the event of signal 2 or signal 3, the GenerateConsoleCtrlEvent()
-   function is used to send a signal to that process. These will not kill
-   GUI processes. It will not (currently) send a signal to remote
-   processes.
-
-   In the event of signal 1 or 4-8, the CreateRemoteThread() function is used
-   after the HANDLE's process has been identified to create a thread
-   within that process. The ExitProcess() function is then sent to that
-   thread.
-
-   In the event of signal 9, the TerminateProcess() function is called. This
-   will almost certainly kill the process, but doesn't give the process a
-   chance to necessarily do any cleanup it might otherwise do.
+= Developer's Notes
+== Removal of Process.fork in release 0.7.0
+   The Process.fork method was originally experimental but it has never
+   been particularly useful in practice. On top of that, it required special
+   implementations of the Process.waitXXX methods, so it was a maintenance
+   issue as well.
    
-== The Process.ppid method
-   In MRI the Process.ppid always returns 0 on MS Windows. With this library
-   it returns the actual parent pid.
+   With Ruby 1.9 now becoming standard and its addition of Process.spawn
+   and friends (and concomitant support for the Process.waitXXX methods) I
+   felt it was time to remove it.
 
-== Differences between Ruby's kill and the Win32 Utils kill
-   Ruby does not currently use the CreateRemoteThread() + ExitProcess()
-   approach which is, according to everything I've read, a cleaner approach.
-   This includes not only online research but also Jeffrey Richter's
-   "Advanced Windows Programming, 3rd Edition."
+   You can still simulate Process.fork if you like using Process.create, which
+   is how it was implemented internally anyway. A better solution might be
+   to follow in the footsteps of ActiveState Perl, which uses native threads
+   to simulate fork on Windows.
 	
-   Also, the way Process.kill handles multiple pids works slightly differently
-   (and better IMHO) in the Win32 Utils version than the way Ruby currently
-   provides.
+== Changes in the custom Process.kill method for 0.7.0
+   The Process.kill method in 0.7.0 more closely matches the spec now, but
+   the internal method for killing processes is still nicer for most signals.
+   With the release of 0.7.0 users can now specify options that provide finer
+   control over how a process is killed. See the documentation for details. 
+
+== The removal of the custom Process.ppid method
+   This was added at some point in the Ruby 1.9 dev cycle so it was removed
+   from this library.
 
-   The reason Process.kill was originally added, in case anyone cares for
-   historical trivia, is that Ruby 1.6.x did not support Process.kill on
-   Windows at all.
-	
-= Notes
-  It is unlikely you will be able to kill system processes with this module.
-  It's probably better that you don't.
-	
 = Known Bugs	
-  None known (though please see the +Details+ section for quirks).  Any
-  bugs should be reported on the project page at
-  http://rubyforge.org/projects/win32utils.
-	
-= Future Plans  
-  Train Process.fork to execute from the point of the call rather than the
-  top of the script (if possible).
-	
-  Other suggestions welcome.
+  None known. Any bugs should be reported on the project page at
+  https://github.com/djberg96/win32-process.
 	
 = License
   Artistic 2.0
 	
 = Copyright
-  (C) 2003-2011 Daniel J. Berger
+  (C) 2003-2012 Daniel J. Berger
   All Rights Reserved
 		
 = Warranty

data/Rakefile

@@ -4,7 +4,7 @@ require 'rake/testtask'
 require 'rbconfig'
 include RbConfig
 
-CLEAN.include('**/*.gem', '**/*.rbc')
+CLEAN.include('**/*.gem', '**/*.rbc', '**/*.log')
 
 namespace :gem do
   desc 'Create the win32-process gem'
@@ -42,6 +42,14 @@ namespace :example do
   end
 end
 
+namespace :test do
+  Rake::TestTask.new(:kill) do |t|
+    t.verbose = true
+    t.warning = true
+    t.test_files = FileList['test/test_win32_process_kill.rb']
+  end
+end
+
 Rake::TestTask.new do |t|
   t.verbose = true
   t.warning = true

data/examples/example_create.rb

@@ -1,35 +1,35 @@
-##########################################################################
-# example_create.rb
-#
-# Simple test program for the Process.create() method. You can run this
-# code via the 'example:create' task.
-##########################################################################
-require "win32/process"
-
-p Process::WIN32_PROCESS_VERSION
-
-struct = Process.create(
-   :app_name         => "notepad.exe",
-   :creation_flags   => Process::DETACHED_PROCESS,
-   :process_inherit  => false,
-   :thread_inherit   => true,
-   :cwd              => "C:\\",
-   :inherit          => true,
-   :environment      => "SYSTEMROOT=#{ENV['SYSTEMROOT']};PATH=C:\\"
-)
-
-p struct
-
-=begin
-# Don't run this from an existing terminal
-pid = Process.create(
-   :app_name       => "cmd.exe",
-   :creation_flags => Process::DETACHED_PROCESS,
-   :startf_flags   => Process::USEPOSITION,
-   :x              => 0,
-   :y              => 0,
-   :title          => "Hi Dan"
-)
-
-puts "Pid of new process: #{pid}"
-=end
+##########################################################################
+# example_create.rb
+#
+# Simple test program for the Process.create() method. You can run this
+# code via the 'example:create' task.
+##########################################################################
+require "win32/process"
+
+p Process::WIN32_PROCESS_VERSION
+
+struct = Process.create(
+   :app_name         => "notepad.exe",
+   :creation_flags   => Process::DETACHED_PROCESS,
+   :process_inherit  => false,
+   :thread_inherit   => true,
+   :cwd              => "C:\\",
+   :inherit          => true,
+   :environment      => "SYSTEMROOT=#{ENV['SYSTEMROOT']};PATH=C:\\"
+)
+
+p struct
+
+=begin
+# Don't run this from an existing terminal
+pid = Process.create(
+   :app_name       => "cmd.exe",
+   :creation_flags => Process::DETACHED_PROCESS,
+   :startf_flags   => Process::USEPOSITION,
+   :x              => 0,
+   :y              => 0,
+   :title          => "Hi Dan"
+)
+
+puts "Pid of new process: #{pid}"
+=end

data/examples/example_kill.rb

@@ -1,34 +1,34 @@
-##########################################################################
-# example_kill.rb
-#
-# Generic test script for futzing around Process.kill. This script
-# requires the sys-proctable library.
-#
-# You can run this example via the 'example:kill' task.
-##########################################################################
-require "win32/process"
-
-begin
-  require "sys/proctable"
-rescue LoadError
-  STDERR.puts "Whoa there!"
-  STDERR.puts "This script requires the sys-proctable package to work."
-  STDERR.puts "You can find it at http://ruby-sysutils.sf.net"
-  STDERR.puts "Exiting..."
-  exit
-end
-
-include Sys
-
-puts "VERSION: " + Process::WIN32_PROCESS_VERSION
-
-IO.popen("notepad")
-sleep 1 # Give it a chance to start before checking for its pid
-
-pids = []
-
-ProcTable.ps{ |s|
-  pids.push(s.pid) if s.cmdline =~ /notepad/i
-}
-
-p Process.kill(9,pids.last)
+##########################################################################
+# example_kill.rb
+#
+# Generic test script for futzing around Process.kill. This script
+# requires the sys-proctable library.
+#
+# You can run this example via the 'example:kill' task.
+##########################################################################
+require "win32/process"
+
+begin
+  require "sys/proctable"
+rescue LoadError
+  STDERR.puts "Whoa there!"
+  STDERR.puts "This script requires the sys-proctable package to work."
+  STDERR.puts "You can find it at http://ruby-sysutils.sf.net"
+  STDERR.puts "Exiting..."
+  exit
+end
+
+include Sys
+
+puts "VERSION: " + Process::WIN32_PROCESS_VERSION
+
+IO.popen("notepad")
+sleep 1 # Give it a chance to start before checking for its pid
+
+pids = []
+
+ProcTable.ps{ |s|
+  pids.push(s.pid) if s.cmdline =~ /notepad/i
+}
+
+p Process.kill(9,pids.last)

data/lib/win32/process/constants.rb

@@ -0,0 +1,105 @@
+module Process::Constants
+  private
+
+  # Priority constants
+
+  ABOVE_NORMAL_PRIORITY_CLASS = 0x0008000
+  BELOW_NORMAL_PRIORITY_CLASS = 0x0004000
+  HIGH_PRIORITY_CLASS         = 0x0000080
+  IDLE_PRIORITY_CLASS         = 0x0000040
+  NORMAL_PRIORITY_CLASS       = 0x0000020
+  REALTIME_PRIORITY_CLASS     = 0x0000010
+
+  # Error constants
+
+  INVALID_HANDLE_VALUE = 0xffffffff
+  ERROR_ACCESS_DENIED  = 0x00000005
+
+  # Process Access Rights
+
+  PROCESS_TERMINATE         = 0x00000001
+  PROCESS_SET_INFORMATION   = 0x00000200
+  PROCESS_QUERY_INFORMATION = 0x00000400
+  PROCESS_ALL_ACCESS        = 0x001F0FFF
+  PROCESS_VM_READ           = 0x00000010
+
+  # Process wait time for Process.kill
+
+  INFINITE = 0xFFFFFFFF
+
+  # Process creation flags
+
+  CREATE_BREAKAWAY_FROM_JOB        = 0x01000000
+  CREATE_DEFAULT_ERROR_MODE        = 0x04000000
+  CREATE_NEW_CONSOLE               = 0x00000010
+  CREATE_NEW_PROCESS_GROUP         = 0x00000200
+  CREATE_NO_WINDOW                 = 0x08000000
+  CREATE_PROTECTED_PROCESS         = 0x00040000
+  CREATE_PRESERVE_CODE_AUTHZ_LEVEL = 0x02000000
+  CREATE_SEPARATE_WOW_VDM          = 0x00000800
+  CREATE_SHARED_WOW_VDM            = 0x00001000
+  CREATE_SUSPENDED                 = 0x00000004
+  CREATE_UNICODE_ENVIRONMENT       = 0x00000400
+  DEBUG_ONLY_THIS_PROCESS          = 0x00000002
+  DEBUG_PROCESS                    = 0x00000001
+  DETACHED_PROCESS                 = 0x00000008
+  INHERIT_PARENT_AFFINITY          = 0x00010000
+
+  STARTF_USESHOWWINDOW    = 0x00000001
+  STARTF_USESIZE          = 0x00000002
+  STARTF_USEPOSITION      = 0x00000004
+  STARTF_USECOUNTCHARS    = 0x00000008
+  STARTF_USEFILLATTRIBUTE = 0x00000010
+  STARTF_RUNFULLSCREEN    = 0x00000020
+  STARTF_FORCEONFEEDBACK  = 0x00000040
+  STARTF_FORCEOFFFEEDBACK = 0x00000080
+  STARTF_USESTDHANDLES    = 0x00000100
+  STARTF_USEHOTKEY        = 0x00000200
+  STARTF_TITLEISLINKNAME  = 0x00000800
+  STARTF_TITLEISAPPID     = 0x00001000
+  STARTF_PREVENTPINNING   = 0x00002000
+
+  LOGON_WITH_PROFILE        = 0x00000001
+  LOGON_NETCREDENTIALS_ONLY = 0x00000002
+
+  SHUTDOWN_NORETRY = 0x00000001
+
+  # Security
+
+  TokenUser   = 1
+  TOKEN_QUERY = 0x00000008
+
+  # Define these for Windows. They are not actually used but are defined
+  # for interface compatibility.
+
+  PRIO_PROCESS = 0
+  PRIO_PGRP    = 1
+  PRIO_USER    = 2
+
+  # Define these for Windows
+
+  RLIMIT_CPU    = 0 # PerProcessUserTimeLimit
+  RLIMIT_FSIZE  = 1 # Hard coded at 4TB - 64K (assumes NTFS)
+  RLIMIT_AS     = 5 # ProcessMemoryLimit
+  RLIMIT_RSS    = 5 # ProcessMemoryLimit
+  RLIMIT_VMEM   = 5 # ProcessMemoryLimit
+
+  # Job constants
+
+  JOB_OBJECT_SET_ATTRIBUTES       = 0x00000002
+  JOB_OBJECT_QUERY                = 0x00000004
+  JOB_OBJECT_LIMIT_PROCESS_TIME   = 0x00000002
+  JOB_OBJECT_LIMIT_PROCESS_MEMORY = 0x00000100
+  JobObjectExtendedLimitInformation = 9
+
+  # Console Events
+
+  CTRL_C_EVENT     = 0
+  CTRL_BREAK_EVENT = 1
+
+  # Miscellaneous
+
+  HANDLE_FLAG_INHERIT     = 0x00000001
+  SEM_FAILCRITICALERRORS  = 0x00000001
+  SEM_NOGPFAULTERRORBOX   = 0x00000002
+end

data/lib/win32/process/functions.rb

@@ -0,0 +1,66 @@
+if RUBY_PLATFORM == 'java'
+  require 'rubygems'
+  gem 'ffi'
+end
+
+require 'ffi'
+
+module Process::Functions
+  module FFI::Library
+    # Wrapper method for attach_function + private
+    def attach_pfunc(*args)
+      attach_function(*args)
+      private args[0]
+    end
+  end
+
+  extend FFI::Library
+
+  ffi_lib :kernel32
+
+  attach_pfunc :CloseHandle, [:ulong], :bool
+  attach_pfunc :GenerateConsoleCtrlEvent, [:ulong, :ulong], :bool
+  attach_pfunc :GetCurrentProcess, [], :ulong
+  attach_pfunc :GetModuleHandle, :GetModuleHandleA, [:string], :ulong
+  attach_pfunc :GetProcessAffinityMask, [:ulong, :pointer, :pointer], :bool
+  attach_pfunc :GetPriorityClass, [:ulong], :ulong
+  attach_pfunc :GetProcAddress, [:ulong, :string], :ulong
+  attach_pfunc :IsProcessInJob, [:ulong, :pointer, :pointer], :void
+  attach_pfunc :OpenProcess, [:ulong, :bool, :ulong], :ulong
+  attach_pfunc :SetHandleInformation, [:ulong, :ulong, :ulong], :bool
+  attach_pfunc :SetErrorMode, [:uint], :uint
+  attach_pfunc :SetPriorityClass, [:ulong, :ulong], :bool
+  attach_pfunc :TerminateProcess, [:ulong, :uint], :bool
+  attach_pfunc :WaitForSingleObject, [:ulong, :ulong], :ulong
+
+  attach_pfunc :CreateRemoteThread,
+    [:ulong, :pointer, :size_t, :ulong, :pointer, :ulong, :pointer], :ulong
+
+  attach_pfunc :GetVolumeInformationA,
+    [:string, :pointer, :ulong, :pointer, :pointer, :pointer, :pointer, :ulong], :bool
+
+  attach_pfunc :CreateProcessW,
+    [:buffer_in, :buffer_in, :pointer, :pointer, :bool,
+     :ulong, :buffer_in, :buffer_in, :pointer, :pointer], :bool
+
+  attach_pfunc :AssignProcessToJobObject, [:ulong, :ulong], :bool
+  attach_pfunc :CreateJobObjectA, [:pointer, :string], :ulong
+  attach_pfunc :OpenJobObjectA, [:ulong, :bool, :string], :ulong
+  attach_pfunc :QueryInformationJobObject, [:ulong, :int, :pointer, :ulong, :pointer], :bool
+  attach_pfunc :SetInformationJobObject, [:ulong, :int, :pointer, :ulong], :bool
+
+  ffi_lib :advapi32
+
+  attach_pfunc :ConvertSidToStringSidA, [:buffer_in, :pointer], :bool
+  attach_pfunc :GetTokenInformation, [:ulong, :int, :pointer, :ulong, :pointer], :bool
+  attach_pfunc :OpenProcessToken, [:ulong, :ulong, :pointer], :bool
+
+  attach_pfunc :CreateProcessWithLogonW,
+    [:buffer_in, :buffer_in, :buffer_in, :ulong, :buffer_in, :buffer_in,
+     :ulong, :buffer_in, :buffer_in, :pointer, :pointer], :bool
+
+  ffi_lib FFI::Library::LIBC
+
+  attach_pfunc :get_errno, :_get_errno, [:pointer], :int
+  attach_pfunc :get_osfhandle, :_get_osfhandle, [:int], :ulong
+end

data/lib/win32/process/helper.rb

@@ -0,0 +1,13 @@
+class String
+  # Convert a regular string to a wide character string. This does not
+  # modify the receiver.
+  def to_wide_string
+    (self + 0.chr).encode('UTF-16LE')
+  end
+
+  # Convert a regular string to a wide character string. This modifies
+  # the receiver.
+  def to_wide_string!
+    replace((self + 0.chr).encode('UTF-16LE'))
+  end
+end

data/lib/win32/process/structs.rb

@@ -0,0 +1,103 @@
+if RUBY_PLATFORM == 'java'
+  require 'rubygems'
+  gem 'ffi'
+end
+
+require 'ffi'
+
+module Process::Structs
+  extend FFI::Library
+
+  private
+
+  # sizeof(LARGE_INTEGER) == 8
+  class LARGE_INTEGER < FFI::Union
+    layout(:QuadPart, :long_long)
+  end
+
+  # sizeof(IO_COUNTERS) == 48
+  class IO_COUNTERS < FFI::Struct
+    layout(
+      :ReadOperationCount, :ulong_long,
+      :WriteOperationCount, :ulong_long,
+      :OtherOperationCount, :ulong_long,
+      :ReadTransferCount, :ulong_long,
+      :WriteTransferCount, :ulong_long,
+      :OtherTransferCount, :ulong_long
+    )
+  end
+
+  class JOBJECT_BASIC_LIMIT_INFORMATION < FFI::Struct
+    layout(
+      :PerProcessUserTimeLimit, LARGE_INTEGER,
+      :PerJobUserTimeLimit, LARGE_INTEGER,
+      :LimitFlags, :ulong,
+      :MinimumWorkingSetSize, :size_t,
+      :MaximumWorkingSetSize, :size_t,
+      :ActiveProcessLimit, :ulong,
+      :Affinity, :pointer,
+      :PriorityClass, :ulong,
+      :SchedulingClass, :ulong
+    )
+  end
+
+  class JOBJECT_EXTENDED_LIMIT_INFORMATION < FFI::Struct
+    layout(
+      :BasicLimitInformation, JOBJECT_BASIC_LIMIT_INFORMATION,
+      :IoInfo, IO_COUNTERS,
+      :ProcessMemoryLimit, :size_t,
+      :JobMemoryLimit, :size_t,
+      :PeakProcessMemoryUsed, :size_t,
+      :PeakJobMemoryUsed, :size_t
+    )
+  end
+
+  class SECURITY_ATTRIBUTES < FFI::Struct
+    layout(
+      :nLength, :ulong,
+      :lpSecurityDescriptor, :pointer,
+      :bInheritHandle, :bool
+    )
+  end
+
+  # sizeof(STARTUPINFO) == 68
+  class STARTUPINFO < FFI::Struct
+    layout(
+      :cb, :ulong,
+      :lpReserved, :string,
+      :lpDesktop, :string,
+      :lpTitle, :string,
+      :dwX, :ulong,
+      :dwY, :ulong,
+      :dwXSize, :ulong,
+      :dwYSize, :ulong,
+      :dwXCountChars, :ulong,
+      :dwYCountChars, :ulong,
+      :dwFillAttribute, :ulong,
+      :dwFlags, :ulong,
+      :wShowWindow, :short,
+      :cbReserved2, :short,
+      :lpReserved2, :pointer,
+      :hStdInput, :ulong,
+      :hStdOutput, :ulong,
+      :hStdError, :ulong
+    )
+  end
+
+  class PROCESS_INFORMATION < FFI::Struct
+    layout(
+      :hProcess, :ulong,
+      :hThread, :ulong,
+      :dwProcessId, :ulong,
+      :dwThreadId, :ulong
+    )
+  end
+
+  # Used by Process.create
+  ProcessInfo = Struct.new("ProcessInfo",
+    :process_handle,
+    :thread_handle,
+    :process_id,
+    :thread_id
+  )
+end