ffi-libfuse 0.0.1.rctest12 → 0.1.0.rc20220550

data/lib/ffi/libfuse/fuse_operations.rb

@@ -12,19 +12,24 @@ require_relative '../flock'
 require_relative 'thread_pool'
 require_relative '../stat'
 require_relative '../struct_array'
+require_relative '../encoding'
 require_relative 'fuse_callbacks'
 
 module FFI
   # Ruby FFI Binding for [libfuse](https://github.com/libfuse/libfuse)
   module Libfuse
+    # All paths are encoded in ruby's view of the filesystem encoding
+    typedef Encoding.for('filesystem'), :fs_string
+
     # typedef int (*fuse_fill_dir_t) (void *buf, const char *name, const struct stat *stbuf, off_t off);
-    fill_dir_t_args = [:pointer, :string, Stat.by_ref, :off_t]
+    fill_dir_t_args = [:pointer, :fs_string, Stat.by_ref, :off_t]
     if FUSE_MAJOR_VERSION > 2
       enum :fuse_readdir_flags, [:fuse_readdir_plus, (1 << 0)]
       enum :fuse_fill_dir_flags, [:fuse_fill_dir_plus, (1 << 1)]
       fill_dir_t_args << :fuse_fill_dir_flags
     end
 
+    bitmask :fuse_ioctl_flags, %i[compat unrestricted retry dir]
     bitmask :lock_op, [:lock_sh, 0, :lock_ex, 2, :lock_nb, 4, :lock_un, 8]
     bitmask :falloc_mode, %i[keep_size punch_hole no_hide_stale collapse_range zero_range insert_range unshare_range]
     bitmask :flags_mask, %i[nullpath_ok nopath utime_omit_ok] if FUSE_MAJOR_VERSION < 3
@@ -33,7 +38,7 @@ module FFI
 
     # The file system operations as specified in libfuse.
     #
-    # All Callback and Configuration methods are optional, but some are essential for a useful filesystem
+    # All Callback methods are optional, but some are essential for a useful filesystem
     # e.g. {getattr},{readdir}
     #
     # Almost all callback operations take a path which can be of any length and will return 0 for success, or raise a
@@ -144,7 +149,7 @@ module FFI
       #  @return [Integer] 0 for success or -ve errno
 
       # int (*symlink) (const char *, const char *);
-      op[:symlink] = [:string]
+      op[:symlink] = [:fs_string]
 
       # @!method rename(from_path,to_path)
       #  @abstract
@@ -155,7 +160,7 @@ module FFI
       #  @return [Integer] 0 for success or -ve errno
 
       # int (*rename) (const char *, const char *);
-      op[:rename] = [:string]
+      op[:rename] = [:fs_string]
 
       # @!method link(path,target)
       #  @abstract
@@ -166,7 +171,7 @@ module FFI
       #  @return [Integer] 0 for success or -ve errno
 
       # int (*link) (const char *, const char *);
-      op[:link] = [:string]
+      op[:link] = [:fs_string]
 
       # @!method chmod(path,mode,fuse_file_info=nil)
       #  @abstract
@@ -660,18 +665,21 @@ module FFI
         #  @param [Integer] cmd
         #  @param [FFI::Pointer] arg
         #  @param [FuseFileInfo] fuse_file_info
-        #  @param [Integer] flags
-        #  @param [FFI::Pointer] data
+        #  @param [Array<Symbol>] flags
         #
-        #  flags will have FUSE_IOCTL_COMPAT set for 32bit ioctls in 64bit environment.  The size and direction of data
-        #  is determined by _IOC_*() decoding of cmd.  For _IOC_NONE, data will be NULL, for _IOC_WRITE data is out
-        #  area, for _IOC_READ in area and if both are set in/out area.  In all non-NULL cases, the area is of
-        #  _IOC_SIZE(cmd) bytes.
+        #    - :compat       32bit compat ioctl on 64bit machine
+        #    - :unrestricted not restricted to well-formed ioctls, retry allowed (lowlevel fuse)
+        #    - :retry        retry with new iovecs (lowlevel fuse)
+        #    - :dir          is a directory file handle
         #
-        #  If flags has FUSE_IOCTL_DIR then the fuse_file_info refers to a directory file handle.
+        #  @param [FFI::Pointer] data
+        #
+        #  The size and direction of data is determined by _IOC_*() decoding of cmd.  For _IOC_NONE, data will be NULL,
+        #  for _IOC_WRITE data is out area, for _IOC_READ in area and if both are set in/out area.  In all non-NULL
+        #  cases, the area is of _IOC_SIZE(cmd) bytes.
 
         # int (*ioctl) (const char *, int cmd, void *arg, struct fuse_file_info *, unsigned int flags, void *data);
-        op[:ioctl] = [:int, :pointer, FuseFileInfo.by_ref, :uint, :pointer]
+        op[:ioctl] = [:int, :pointer, FuseFileInfo.by_ref, :fuse_ioctl_flags, :pointer]
 
         # @!method poll(path,fuse_file_info,ph,reventsp)
         #  @abstract
@@ -697,8 +705,9 @@ module FFI
         #  @abstract
         #  Write contents of buffer to an open file
         #
-        #  Similar to the write() method, but data is supplied in a generic buffer.  Use fuse_buf_copy() to transfer
-        #  data to the destination.
+        #  Similar to the write() method, but data is supplied in a generic buffer.
+        #  Use {FuseBufVec#copy_to_fd} to copy data to an open file descriptor, or {FuseBufVec#copy_to_str} to extract
+        #  string data from the buffer
         #
         #  @param [String] path
         #  @param [FuseBufVec] buf
@@ -804,8 +813,8 @@ module FFI
           # );
           op[:copy_file_range] =
             callback [
-              :string, FuseFileInfo.by_ref, :off_t,
-              :string, FuseFileInfo.by_ref, :off_t,
+              :fs_string, FuseFileInfo.by_ref, :off_t,
+              :fs_string, FuseFileInfo.by_ref, :off_t,
               :size_t, :int
             ], :ssize_t
 
@@ -820,7 +829,7 @@ module FFI
           #  @see lseek(2)
 
           # off_t (*lseek) (const char *, off_t off, int whence, struct fuse_file_info *);
-          op[:lseek] = callback [:string, :off_t, Flock::Enums::SeekWhence, FuseFileInfo.by_ref], :off_t
+          op[:lseek] = callback [:fs_string, :off_t, Flock::Enums::SeekWhence, FuseFileInfo.by_ref], :off_t
         end
       end
 
@@ -829,7 +838,7 @@ module FFI
       layout_data = op.transform_values do |v|
         if v.is_a?(Array) && !v.last.is_a?(Integer)
           # A typical fuse callback
-          callback([:string] + v, :int)
+          callback([:fs_string] + v, :int)
         else
           v
         end
@@ -865,6 +874,21 @@ module FFI
         fuse_flags.concat(delegate.fuse_flags) if delegate.respond_to?(:fuse_flags)
         send(:[]=, :flags, fuse_flags.uniq)
       end
+
+      # @!visibility private
+      def fuse_callbacks
+        self.class.fuse_callbacks
+      end
+
+      # @return [Set<Symbol>] list of callback methods
+      def self.fuse_callbacks
+        @fuse_callbacks ||= Set.new(members - [:flags])
+      end
+
+      # @return [Set<Symbol>] list of path callback methods
+      def self.path_callbacks
+        @path_callbacks ||= fuse_callbacks - %i[init destroy]
+      end
     end
   end
 end

data/lib/ffi/libfuse/fuse_version.rb

@@ -9,15 +9,18 @@ module FFI
   module Libfuse
     extend FFI::Library
 
+    libs =
+      case FFI::Platform::NAME
+      when 'x86_64-darwin'
+        %w[libfuse.2.dylib]
+      else
+        %w[libfuse3.so.3 libfuse.so.2]
+      end
     # The fuse library to load from 'LIBFUSE' environment variable if set, otherwise prefer Fuse3 over Fuse2
-    LIBFUSE = ENV['LIBFUSE'] || %w[libfuse3.so.3 libfuse.so.2]
+    LIBFUSE = ENV.fetch('LIBFUSE', libs)
     ffi_lib(LIBFUSE)
 
-    # @!scope class
-    # @!method fuse_version()
-    # @return [Integer] the fuse version
-    # See {FUSE_VERSION} which captures this result in a constant
-
+    # @!visibility private
     attach_function :fuse_version, [], :int
 
     # prior to 3.10 this is Major * 10 + Minor, after 3.10 and later is Major * 100 + Minor
@@ -36,6 +39,7 @@ module FFI
       require_relative '../gnu_extensions'
 
       extend(GNUExtensions)
+
       # libfuse2 has busted symbols
       ffi_lib_versions(%w[FUSE_2.9.1 FUSE_2.9 FUSE_2.8 FUSE_2.7 FUSE_2.6 FUSE_2.5 FUSE_2.4 FUSE_2.3 FUSE_2.2])
     end

data/lib/ffi/libfuse/main.rb

@@ -14,7 +14,8 @@ module FFI
         # This function:
         #
         # - parses command line options - see {fuse_parse_cmdline}
-        #   and exits immediately if help or version options were processed
+        #   exiting immediately if help or version options were processed
+        # - calls {#fuse_debug}, {#fuse_options}, {#fuse_configure} if implemented by operations
         # - installs signal handlers for INT, HUP, TERM to unmount and exit filesystem
         # - installs custom signal handlers if operations implements {fuse_traps}
         # - creates a fuse handle mounted with registered operations - see {fuse_create}
@@ -22,7 +23,7 @@ module FFI
         #
         # @param [Array<String>] argv mount.fuse arguments
         #   expects progname, mountpoint, options....
-        # @param [FuseArgs] args
+        # @param [FuseArgs|Array<String>] args
         #   alternatively constructed args
         # @param [Object|FuseOperations] operations
         #  something that responds to the fuse callbacks and optionally our abstract configuration methods
@@ -30,13 +31,18 @@ module FFI
         #  any data to be made available to the {FuseOperations#init} callback
         #
         # @return [Integer] suitable for process exit code
-        def fuse_main(*argv, operations:, args: argv, private_data: nil)
+        def fuse_main(*argv, operations:, args: argv.any? ? argv : [$0, *ARGV], private_data: nil)
           run_args = fuse_parse_cmdline(args: args, handler: operations)
           return 2 unless run_args
 
           fuse_args = run_args.delete(:args)
           mountpoint = run_args.delete(:mountpoint)
 
+          return 3 unless fuse_configure(operations: operations, **run_args)
+
+          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 run_args[:show_help] || run_args[:show_version]
@@ -44,16 +50,15 @@ module FFI
 
           return unless fuse
 
-          warn run_args.to_s if run_args[:debug]
-
           fuse.run(**run_args)
         end
+        alias main fuse_main
 
         # 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
-        # - parses custom options if handler implements {fuse_options} and {fuse_opt_proc}
+        # - calls {fuse_options} for custom option processing if implemented by handler
         # - records signal handlers if operations implements {fuse_traps}
         # - parses standard fuse mount options
         #
@@ -63,33 +68,25 @@ module FFI
         #   alternatively constructed args
         # @param [Object] handler
         #   something that responds to our abstract configuration methods
-        # @param [Object] private_data passed to handler.fuse_opt_proc
-        #
         # @return [Hash<Symbol,Object>]
-        #   * fsname [String]: the fsspec from /etc/fstab
         #   * 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}
-        def fuse_parse_cmdline(*argv, args: argv, handler: nil, private_data: nil)
+        def fuse_parse_cmdline(*argv, args: argv, handler: nil)
           args = fuse_init_args(args)
 
           # Parse args and print cmdline help
           run_args = Fuse.parse_cmdline(args, handler: handler)
+          return nil unless run_args
 
-          # process custom options
-          if %i[fuse_options fuse_opt_proc].all? { |m| handler.respond_to?(m) }
-            parse_ok = args.parse!(handler.fuse_options, private_data) do |*p_args|
-              handler.fuse_opt_proc(*p_args)
-            end
-            return unless parse_ok
-          end
+          return nil if handler.respond_to?(:fuse_options) && !handler.fuse_options(args)
 
           run_args[:traps] = handler.fuse_traps if handler.respond_to?(:fuse_traps)
 
-          args.parse!(RUN_OPTIONS, run_args) { |*opt_args| hash_opt_proc(*opt_args, discard: %i[native max_threads]) }
+          return nil unless parse_run_options(args, run_args)
 
           run_args[:args] = args
           run_args
@@ -105,18 +102,24 @@ module FFI
           fuse if fuse.mounted?
         end
 
-        # Helper fuse_opt_proc function to capture options into a hash
-        #
-        # See {FuseArgs.parse!}
-        def hash_opt_proc(hash, arg, key, _out, discard: [])
-          return :keep if %i[unmatched non_option].include?(key)
+        # @!visibility private
 
-          hash[key] = arg =~ /=/ ? arg.split('=', 2).last : true
-          discard.include?(key) ? :discard : :keep
+        def fuse_configure(operations:, show_help: false, show_version: false, **_)
+          return true unless operations.respond_to?(:fuse_configure) && !show_help && !show_version
+
+          # Provide sensible values for FuseContext in case this is referenced during configure
+          FFI::Libfuse::FuseContext.overrides do
+            operations.fuse_configure
+            true
+          rescue Error => e
+            warn e.message
+            false
+          rescue StandardError, ScriptError => e
+            warn "#{e.class.name}: #{e.message}\n\t#{e.backtrace.join("\n\t")}"
+            false
+          end
         end
 
-        # @!visibility private
-
         # Version text
         def version
           "#{name}: #{VERSION}"
@@ -131,6 +134,7 @@ module FFI
             unless args.size <= 2 || args[1]&.start_with?('-') || args[2]&.start_with?('-')
               args[1] = "-ofsname=#{args[1]}"
             end
+            warn "FuseArgs: #{args.join(' ')}" if args.include?('-d')
             args = FuseArgs.create(*args)
           end
 
@@ -138,23 +142,54 @@ module FFI
 
           raise ArgumentError "fuse main args: must be Array<String> or #{FuseArgs.class.name}"
         end
+
+        private
+
+        def parse_run_options(args, run_args)
+          args.parse!(RUN_OPTIONS) do |key:, value:, **|
+            run_args[key] = value
+            next :keep if (STANDARD_OPTIONS.values + %i[remember]).include?(key)
+
+            :discard
+          end
+        end
       end
 
       # @!group Abstract Configuration
 
-      # @!method fuse_options
+      # @!method fuse_options(args)
       #  @abstract
-      #  @return [Hash] custom option schema
-      #  @see FuseArgs#parse!
-
-      # @!method fuse_opt_proc(data,arg,key,out)
-      #  @abstract
-      #  Process custom options
+      #  Called to allow filesystem to handle custom options and observe standard mount options #
+      #  @param [FuseArgs] args
+      #  @return [Boolean] true if args parsed successfully
       #  @see FuseArgs#parse!
+      #  @example
+      #    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::FuseArgs::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
 
       # @!method fuse_traps
       #  @abstract
-      #  @return [Hash] map of signal name or number to signal handler as per Signal.trap
+      #  @return [Hash<String|Symbol|Integer,String|Proc>]
+      #    map of signal name or number to signal handler as per Signal.trap
+      #  @example
+      #    def fuse_traps
+      #      { HUP: ->() { reload() }}
+      #    end
 
       # @!method fuse_version
       #  @abstract
@@ -162,14 +197,22 @@ module FFI
 
       # @!method fuse_help
       #  @abstract
-      #  @return [String] help text to explain custom options to show with -h option
+      #  Called as part of generating output for the -h option
+      #  @return [String] help text to explain custom options
 
       # @!method fuse_debug(enabled)
       #  @abstract
-      #  Indicate to the filesystem whether debugging option is in use.
+      #  Called to indicate to the filesystem whether debugging option is in use.
       #  @param [Boolean] enabled if -d option is in use
       #  @return [void]
 
+      # @!method fuse_configure
+      #  @abstract
+      #  Called immediately before the filesystem is mounted, after options have been parsed
+      #
+      #  @raise [Error] to prevent the mount from proceeding
+      #  @return [void]
+
       # @!endgroup
 
       # @!visibility private

data/lib/ffi/libfuse/version.rb

@@ -3,6 +3,6 @@
 module FFI
   # Ruby FFI Binding for [libfuse](https://github.com/libfuse/libfuse)
   module Libfuse
-    VERSION = '0.0.1'
+    VERSION = '0.1.0'
   end
 end

data/lib/ffi/libfuse.rb

@@ -5,20 +5,29 @@ require_relative 'libfuse/fuse2' if FFI::Libfuse::FUSE_MAJOR_VERSION == 2
 require_relative 'libfuse/fuse3' if FFI::Libfuse::FUSE_MAJOR_VERSION == 3
 require_relative 'libfuse/main'
 require_relative 'libfuse/adapter'
+require_relative 'libfuse/filesystem'
 require_relative 'devt'
 
 module FFI
   # Ruby FFI Binding for [libfuse](https://github.com/libfuse/libfuse)
   module Libfuse
+    # Filesystems can raise this error to indicate errors from filesystem users
+    class Error < StandardError; end
+
+    # Opinionated default args for {.main}.
+    #
+    # Filesystems that want full control (eg to take advantage of multi-threaded operations) should call
+    #  {Main.fuse_main} instead
+    # @note These may change between major versions
+    DEFAULT_ARGS = [$0, '-s', '-odefault_permissions', *ARGV].freeze
+
     class << self
       # Filesystem entry point
-      # @note This main function defaults to single-threaded operation by injecting the '-s' option. Pass `$0,*ARGV`
-      #   if your filesystem can usefully support multi-threaded operation.
-      #
       # @see Main.fuse_main
-      def fuse_main(*argv, operations:, args: argv.any? ? argv : [$0, '-s', *ARGV], private_data: nil)
+      def fuse_main(*argv, operations:, args: argv.any? ? argv : DEFAULT_ARGS, private_data: nil)
         Main.fuse_main(args: args, operations: operations, private_data: private_data) || -1
       end
+      alias main fuse_main
     end
   end
 end

data/lib/ffi/ruby_object.rb

@@ -74,7 +74,7 @@ module FFI
       end
 
       def finalizer(*keys)
-        proc { keys.each { cache.delete(key) } }
+        proc { keys.each { |k| cache.delete(k) } }
       end
 
       def store(obj)

data/lib/ffi/stat/constants.rb

@@ -25,5 +25,14 @@ module FFI
 
     # Socket
     S_IFSOCK = 0o140000
+
+    # SetUID
+    S_ISUID  = 0o004000
+
+    # SetGID
+    S_ISGID  = 0o002000
+
+    # Sticky Bit
+    S_ISVTX  = 0o001000
   end
 end

data/lib/ffi/stat/native.rb

@@ -5,7 +5,6 @@ require_relative 'time_spec'
 
 module FFI
   class Stat
-    # Native (and naked) stat from stat.h
     # @!visibility private
     class Native < Struct
       case Platform::NAME
@@ -17,31 +16,62 @@ module FFI
                :st_mode,    :mode_t,
                :st_uid,     :uid_t,
                :st_gid,     :gid_t,
-               :__pad0,     :int,
+               :__pad0,     :uint,
                :st_rdev,    :dev_t,
                :st_size,    :off_t,
                :st_blksize, :blksize_t,
                :st_blocks,  :blkcnt_t,
                :st_atimespec, TimeSpec,
                :st_mtimespec, TimeSpec,
-               :st_ctimespec, TimeSpec
+               :st_ctimespec, TimeSpec,
+               :unused, [:long, 3]
+
+        [['', :string], ['l', :string], ['f', :int]].each do |(prefix, ftype)|
+          native_func = "native_#{prefix}stat".to_sym
+          lib_func = "#{prefix}stat".to_sym
+          begin
+            ::FFI::Stat.attach_function native_func, lib_func, [ftype, by_ref], :int
+          rescue FFI::NotFoundError
+            # gLibc 2.31 (Ubuntu focal) does not export these functions, it maps them to __xstat variants
+            native_xfunc = "native_#{prefix}xstat".to_sym
+            lib_xfunc = "__#{prefix}xstat".to_sym
+            ::FFI::Stat.attach_function native_xfunc, lib_xfunc, [:int, ftype, by_ref], :int
+            # 1 is 64 bit versions of struct stat,  3 is 32 bit
+            ::FFI::Stat.define_singleton_method(native_func) { |file, buf| send(native_xfunc, 1, file, buf) }
+          end
+        end
 
-      when 'x65_64-darwin'
+      when 'x86_64-darwin', 'aarch64-darwin'
+        #  man stat - this is stat with 64 bit inodes.
         layout :st_dev,       :dev_t,
-               :st_ino,       :uint32,
                :st_mode,      :mode_t,
                :st_nlink,     :nlink_t,
+               :st_ino,       :ino_t,
                :st_uid,       :uid_t,
                :st_gid,       :gid_t,
                :st_rdev,      :dev_t,
                :st_atimespec, TimeSpec,
                :st_mtimespec, TimeSpec,
                :st_ctimespec, TimeSpec,
+               :st_birthtimespec, TimeSpec,
                :st_size,      :off_t,
                :st_blocks,    :blkcnt_t,
                :st_blksize,   :blksize_t,
                :st_flags,     :uint32,
-               :st_gen,       :uint32
+               :st_gen,       :uint32,
+               :st_lspare,     :int32,
+               :st_gspare,     :int64
+
+        begin
+          # TODO: these functions are deprecated, but at least on Cataline -> Monterey the old stat functions
+          #       use the stat struct *without* 64 bit inodes, but macfuse is compiled with 64 bit inodes
+          ::FFI::Stat.attach_function :native_stat, :stat64, [:string, by_ref], :int
+          ::FFI::Stat.attach_function :native_lstat, :lstat64, [:string, by_ref], :int
+          ::FFI::Stat.attach_function :native_fstat, :fstat64, [:int, by_ref], :int
+        rescue FFI::NotFoundError
+          # these are only used in testing
+        end
+
       else
         raise NotImplementedError, "FFI::Stat not implemented for FFI::Platform #{Platform::NAME}"
       end

data/lib/ffi/stat/time_spec.rb

@@ -14,14 +14,27 @@ module FFI
       # Special nsec value representing a request to omit setting this time - see utimensat(2)
       UTIME_OMIT = (1 << 30) - 2
 
-      # A fixed TimeSpec representing the current time
-      def self.now
-        @now ||= new.set_time(0, UTIME_NOW)
-      end
+      class << self
+        # A fixed TimeSpec representing the current time
+        def now
+          @now ||= new.set_time(0, UTIME_NOW)
+        end
+
+        # A fixed TimeSpec representing a request to omit setting this time
+        def omit
+          @omit ||= new.set_time(0, UTIME_OMIT)
+        end
 
-      # A fixed TimeSpec representing a request to omit setting this time
-      def self.omit
-        @omit ||= new.set_time(0, UTIME_OMIT)
+        # @param [Array<TimeSpec>] times
+        # @param [Integer] size
+        # @return [Array<TimeSpec>] list of times filled out to size with TimeSpec.now if times was empty,
+        #   otherwise with TimeSpec.omit
+        def fill_times(times, size = times.size)
+          return times unless times.size < size
+          return Array.new(size, now) if times.empty?
+
+          times.dup.fill(omit, times.size..size - times.size) if times.size < size
+        end
       end
 
       layout(
@@ -45,15 +58,14 @@ module FFI
 
       # @overload set_time(time)
       #  @param [Time] time
-      #  @return [TimeSpec] self
+      #  @return [self]
       # @overload set_time(sec,nsec=0)
       #  @param [Integer] sec number of (nano/micro)seconds from epoch, precision depending on nsec
       #  @param [Symbol|Integer] nsec
       #   - :nsec to treat sec as number of nanoseconds since epoch
       #   - :usec to treat sec as number of microseconds since epoch
       #   - Integer to treat sec as number of seconds since epoch, and nsec as additional nanoseconds
-      #
-      #  @return [TimeSpec] self
+      #  @return [self]
       def set_time(sec, nsec = 0)
         return set_time(sec.to_i, sec.nsec) if sec.is_a?(Time)
 
@@ -95,6 +107,10 @@ module FFI
         Time.at(sec, nsec, :nsec, in: 0).utc
       end
 
+      def to_s(now = nil)
+        time(now).to_s
+      end
+
       # Convert to Integer
       # @param [Time|nil] now
       #   optional value to use if {now?} is true.  If not set then Time.now will be used