Class: UserfaultFD

Inherits:
Object
  • Object
show all
Defined in:
lib/userfaultfd.rb,
lib/userfaultfd.rb,
lib/userfaultfd/handler.rb,
lib/userfaultfd/version.rb,
sig/userfaultfd.rbs,
ext/userfaultfd/userfaultfd.c

Overview

Linux userfaultfd descriptor and capability API.

Defined Under Namespace

Classes: DeadlockError, Error, EventReader, Fault, ForkEvent, Handler, NativeHandler, Region, RemapEvent, RemoveEvent, UnmapEvent, UnsupportedError

Constant Summary collapse

VERSION =

Returns:

  • (String) 
"1.0.0"

Class Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(*args) ⇒ UserfaultFD

Returns a new instance of UserfaultFD.

Parameters:

  • features (Array<Symbol>, nil) —

    features to require; by default fork events are attempted and omitted when the kernel denies permission

  • user_mode_only (Boolean) —

    restrict faults to userspace

  • features: (Array[feature], nil)
  • user_mode_only: (Boolean) 


25
26
27
28
29
30
31
32
33
34
35
 
# File 'lib/userfaultfd.rb', line 25

class UserfaultFD
  class Error < StandardError; end
  class UnsupportedError < Error; end
  class DeadlockError < Error; end

  class << self
    attr_accessor :strict
  end

  self.strict = false
end

Class Attribute Details

.strict ⇒ Boolean

Returns the value of attribute strict.

Returns:

  • (Boolean) 


31
32
33
 
# File 'lib/userfaultfd.rb', line 31

def strict
  @strict
end

Class Method Details

.features(*args) ⇒ Array<Symbol>

Returns features available from the running kernel.

Parameters:

  • user_mode_only: (Boolean)

Returns:

  • (Array<Symbol>) —

    features available from the running kernel



25
26
27
28
29
30
31
32
33
34
35
 
# File 'lib/userfaultfd.rb', line 25

class UserfaultFD
  class Error < StandardError; end
  class UnsupportedError < Error; end
  class DeadlockError < Error; end

  class << self
    attr_accessor :strict
  end

  self.strict = false
end

.supported?(*args) ⇒ Boolean

Returns whether a permitted userfaultfd can be initialized.

Parameters:

  • user_mode_only (Boolean) —

    restrict faults to userspace; set false only on Linux before 5.11 when the caller has the required privilege

  • user_mode_only: (Boolean)

Returns:

  • (Boolean) —

    whether a permitted userfaultfd can be initialized



25
26
27
28
29
30
31
32
33
34
35
 
# File 'lib/userfaultfd.rb', line 25

class UserfaultFD
  class Error < StandardError; end
  class UnsupportedError < Error; end
  class DeadlockError < Error; end

  class << self
    attr_accessor :strict
  end

  self.strict = false
end

Instance Method Details

#backend ⇒ :device, :syscall

Returns:

  • (:device, :syscall) 


613
 
# File 'ext/userfaultfd/userfaultfd.c', line 613

def backend: () -> (:device | :syscall)

#close ⇒ nil

Returns:

  • (nil) 


626
 
# File 'ext/userfaultfd/userfaultfd.c', line 626

def close: () -> nil

#closed? ⇒ Boolean

Returns:

  • (Boolean) 


639
 
# File 'ext/userfaultfd/userfaultfd.c', line 639

def closed?: () -> bool

#enabled_features ⇒ Array<Symbol>

Returns features enabled for this descriptor.

Returns:

  • (Array<Symbol>) —

    features enabled for this descriptor



25
26
27
28
29
30
31
32
33
34
35
 
# File 'lib/userfaultfd.rb', line 25

class UserfaultFD
  class Error < StandardError; end
  class UnsupportedError < Error; end
  class DeadlockError < Error; end

  class << self
    attr_accessor :strict
  end

  self.strict = false
end

#features ⇒ Array[feature]

Returns:

  • (Array[feature]) 


589
 
# File 'ext/userfaultfd/userfaultfd.c', line 589

def features: () -> Array[feature]

#fileno ⇒ Integer

Returns:

  • (Integer) 


620
 
# File 'ext/userfaultfd/userfaultfd.c', line 620

def fileno: () -> Integer

#read_events(*args) ⇒ Array[event]

Parameters:

  • max (Integer)

Returns:

  • (Array[event]) 


1088
 
# File 'ext/userfaultfd/userfaultfd.c', line 1088

def read_events: (?Integer max) -> Array[event]

#register(*args) ⇒ Integer

Returns ioctl bitmask supported for the range.

Parameters:

  • region (UserfaultFD::Region)
  • mode (Symbol, Array<Symbol>) —

    :missing, :wp, or :minor

  • (Region)
  • mode: (register_mode, Array[register_mode])

Returns:

  • (Integer) —

    ioctl bitmask supported for the range



25
26
27
28
29
30
31
32
33
34
35
 
# File 'lib/userfaultfd.rb', line 25

class UserfaultFD
  class Error < StandardError; end
  class UnsupportedError < Error; end
  class DeadlockError < Error; end

  class << self
    attr_accessor :strict
  end

  self.strict = false
end

#start_handler(mode:, io:, source:) ⇒ Handler #start_handler ⇒ Handler

Overloads:

  • #start_handler(mode:, io:, source:) ⇒ Handler

    Parameters:

    • mode: (native_mode)
    • io: (IO, nil)
    • source: (Region, nil)

    Returns:

  • #start_handler ⇒ Handler

    Returns:

Yields:

Yield Parameters:

  • arg0 (event)

Yield Returns:

  • (void) 


45
46
47
 
# File 'lib/userfaultfd.rb', line 45

def start_handler(mode: nil, io: nil, source: nil, &block)
  Handler.new(self, mode: mode, io: io, source: source, &block)
end

#to_io ⇒ IO

Returns:

  • (IO) 


41
42
43
 
# File 'lib/userfaultfd.rb', line 41

def to_io
  IO.for_fd(fileno, autoclose: false)
end

#unregister(region_object) ⇒ nil

Parameters:

Returns:

  • (nil) 


25
26
27
28
29
30
31
32
33
34
35
 
# File 'lib/userfaultfd.rb', line 25

class UserfaultFD
  class Error < StandardError; end
  class UnsupportedError < Error; end
  class DeadlockError < Error; end

  class << self
    attr_accessor :strict
  end

  self.strict = false
end

#writeprotect(*args) ⇒ nil

Parameters:

Returns:

  • (nil) 


911
 
# File 'ext/userfaultfd/userfaultfd.c', line 911

def writeprotect: (Region, enabled: bool) -> nil