Module: FFI::Libfuse::Main

Defined in:
lib/ffi/libfuse/main.rb

Overview

Controls the main run loop for a FUSE filesystem

Abstract Configuration collapse

Class Method Summary collapse

Class Method Details

.default_args(*extra_args) ⇒ Array<String>

Builds default argument list for #fuse_main regardless of being called directly or from mount.fuse3

Parameters:

  • extra_args (Array<String>) —

    additional arguments to add to $0 and *ARGV

Returns:

  • (Array<String>)

See Also:



17
18
19
20
21
22
23
 
# File 'lib/ffi/libfuse/main.rb', line 17

def default_args(*extra_args)
  args = ARGV.dup

  # If called from mount.fuse3 we already have a 'source' argument which should go at args[0]
  args.unshift($0) unless args.size >= 2 && args[0..1].all? { |a| !a.start_with?('-') }
  args.concat(extra_args)
end

.fuse_create(mountpoint, *argv, operations:, args: nil, private_data: nil) ⇒ FuseCommon?

Returns:

  • (FuseCommon) —

    the mounted filesystem handle

  • (nil) —

    if not mounted (eg due to --help or --version, or an error)



107
108
109
110
111
112
113
114
 
# File 'lib/ffi/libfuse/main.rb', line 107

def fuse_create(mountpoint, *argv, operations:, args: nil, private_data: nil)
  args = fuse_init_args(args || argv)

  operations = FuseOperations.new(delegate: operations) unless operations.is_a?(FuseOperations)

  fuse = Fuse.new(mountpoint.to_s, args, operations, private_data)
  fuse if fuse.mounted?
end

.fuse_main(*argv, operations:, args: argv.any? ? argv : default_args, private_data: nil) ⇒ Integer Also known as: main

Main function of FUSE

  • parses command line options - see fuse_parse_cmdline
  • calls #fuse_configure if implemented by operations
  • creates a fuse handle see fuse_create
  • returns 0 if help or version options were processed (ie after all messages have been printed by libfuse)
  • returns 2 if fuse handle is not successfully mounted
  • calls #fuse_traps if implemented by operations
  • calls run on the fuse handle with options from previous steps- see FuseCommon#run

Parameters:

  • argv (Array<String>) —

    mount.fuse arguments expects progname, mountpoint, options....

  • args (FuseArgs|Array<String>) (defaults to: argv.any? ? argv : default_args) —

    alternatively constructed args

  • operations (Object|FuseOperations) —

    something that responds to the fuse callbacks and optionally our abstract configuration methods

  • private_data (Object) (defaults to: nil) —

    any data to be made available to the FuseOperations#init callback

Returns:

  • (Integer) —

    suitable for process exit code



45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/ffi/libfuse/main.rb', line 45

def fuse_main(*argv, operations:, args: argv.any? ? argv : default_args, private_data: nil)
  run_args = fuse_parse_cmdline(args: args, handler: operations)

  fuse_args = run_args.delete(:args)
  mountpoint = run_args.delete(:mountpoint)

  show_only = run_args[:show_help] || run_args[:show_version]

  return 3 if !show_only && !fuse_configure(operations)

  warn "FuseCreate: mountpoint: #{mountpoint}, args: [#{fuse_args.argv.join(' ')}]" if run_args[:debug]
  warn "FuseRun: #{run_args}" if run_args[:debug]

  fuse = fuse_create(mountpoint, args: fuse_args, operations: operations, private_data: private_data)

  return 0 if show_only
  return 2 if !fuse || !mountpoint

  run_args[:traps] = operations.fuse_traps if operations.respond_to?(:fuse_traps)
  fuse.run(**run_args)
end

.fuse_parse_cmdline(*argv, args: argv.any? ? argv : default_args, handler: nil) ⇒ Hash<Symbol,Object>?

Parse command line arguments

  • parses standard command line options (-d -s -h -V) will call #fuse_debug, #fuse_version, #fuse_help if implemented by handler
  • calls #fuse_options for custom option processing if implemented by handler
  • parses standard fuse mount options

Parameters:

  • argv (Array<String>) —

    mount.fuse arguments expects progname, mountpoint, options....

  • args (FuseArgs) (defaults to: argv.any? ? argv : default_args) —

    alternatively constructed args

  • handler (Object) (defaults to: nil) —

    something that responds to our abstract configuration methods

Returns:

  • (Hash<Symbol,Object>) —
    • mountpoint [String]: the mountpoint argument
    • args [FuseArgs]: remaining fuse_args to pass to fuse_create
    • show_help [Boolean]: -h or --help
    • show_version [Boolean]: -v or --version
    • debug [Boolean]: -d
    • others are options to pass to FuseCommon#run
  • (nil) —

    if args are not parsed successfully



89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/ffi/libfuse/main.rb', line 89

def fuse_parse_cmdline(*argv, args: argv.any? ? argv : default_args, handler: nil)
  args = fuse_init_args(args)

  # Parse args and print cmdline help
  run_args = Fuse.parse_cmdline(args, handler: handler)

  handler.fuse_options(args) if handler.respond_to?(:fuse_options)

  parse_run_options(args, run_args)

  run_args[:args] = args
  run_args
rescue Error
  nil
end

Instance Method Details

#fuse_configure ⇒ void

This method is abstract.

This method returns an undefined value.

Called immediately before the filesystem is mounted, after options have been parsed (eg to validate required options)

Raises:

  • (Error) —

    to prevent the mount from proceeding




# File 'lib/ffi/libfuse/main.rb', line 216

#fuse_debug(enabled) ⇒ void

This method is abstract.

This method returns an undefined value.

Called to indicate to the filesystem whether debugging option is in use.

Parameters:

  • enabled (Boolean) —

    if -d option is in use




# File 'lib/ffi/libfuse/main.rb', line 210

#fuse_help ⇒ String

This method is abstract.

Called as part of generating output for the -h option

Returns:

  • (String) —

    help text to explain custom options




# File 'lib/ffi/libfuse/main.rb', line 205

#fuse_options(args) ⇒ void

This method is abstract.

This method returns an undefined value.

Called to allow filesystem to handle custom options and observe standard mount options #

Examples:

OPTIONS = { 'config=' => :config, '-c ' => :config }
def fuse_options(args)
   args.parse!(OPTIONS) do |key:, value:, out:, **opts|

      # raise errors for invalid config
      raise FFI::Libfuse::Error, "Invalid config" unless valid_config?(key,value)

      # Configure the file system
      @config = value if key == :config

      #Optionally manipulate other arguments for fuse_mount() based on the current argument and state
      out.add('-oopt=val')

      # Custom options must be marked :handled otherwise fuse_mount() will fail with unknown arguments
      :handled
   end
end

Parameters:

Raises:

  • (Error) —

    if there is an error parsing the options

See Also:




# File 'lib/ffi/libfuse/main.rb', line 163

#fuse_traps ⇒ Hash<String|Symbol|Integer,String|Proc>

This method is abstract.

Passed to FuseCommon#run to allow filesystem to handle custom signal traps. These traps are merged over those from FuseCommon#default_traps

Examples:

def fuse_traps
  { HUP: ->() { reload() }}
end

Returns:

  • (Hash<String|Symbol|Integer,String|Proc>) —

    map of signal name or number to signal handler as per Signal.trap




# File 'lib/ffi/libfuse/main.rb', line 189

#fuse_version ⇒ String

This method is abstract.

Called as part of generating output for the -V option

Returns:

  • (String) —

    a custom version string to output with -V option




# File 'lib/ffi/libfuse/main.rb', line 200