# module Puppet::Util

### Constants

AbsolutePathPosix
AbsolutePathWindows

### Public Class Methods

absolute_path?(path, platform=nil) click to toggle source

    # File lib/puppet/util.rb, line 241
    def absolute_path?(path, platform=nil)
      # Ruby only sets File::ALT_SEPARATOR on Windows and the Ruby standard
      # library uses that to test what platform it's on.  Normally in Puppet we
      # would use Puppet.features.microsoft_windows?, but this method needs to
      # be called during the initialization of features so it can't depend on
      # that.
      platform ||= Puppet::Util::Platform.windows? ? :windows : :posix
      regex = case platform
              when :windows
                AbsolutePathWindows
              when :posix
                AbsolutePathPosix
              else
                raise Puppet::DevError, "unknown platform #{platform} in absolute_path"
              end

      !! (path =~ regex)
    end

activerecord_version() click to toggle source

    # File lib/puppet/util.rb, line 28
    def self.activerecord_version
      if (defined?(::ActiveRecord) and defined?(::ActiveRecord::VERSION) and defined?(::ActiveRecord::VERSION::MAJOR) and defined?(::ActiveRecord::VERSION::MINOR))
        ([::ActiveRecord::VERSION::MAJOR, ::ActiveRecord::VERSION::MINOR].join('.').to_f)
      else
        0
      end
    end

benchmark(*args) { || ... } click to toggle source

    # File lib/puppet/util.rb, line 154
    def benchmark(*args)
      msg = args.pop
      level = args.pop
      object = nil

      if args.empty?
        if respond_to?(level)
          object = self
        else
          object = Puppet
        end
      else
        object = args.pop
      end

      raise Puppet::DevError, "Failed to provide level to :benchmark" unless level

      unless level == :none or object.respond_to? level
        raise Puppet::DevError, "Benchmarked object does not respond to #{level}"
      end

      # Only benchmark if our log level is high enough
      if level != :none and Puppet::Util::Log.sendlevel?(level)
        result = nil
        seconds = Benchmark.realtime {
          yield
        }
        object.send(level, msg + (" in %0.2f seconds" % seconds))
        return seconds
      else
        yield
      end
    end

binread(file) click to toggle source

Because IO#binread is only available in 1.9

    # File lib/puppet/util.rb, line 360
    def binread(file)
      File.open(file, 'rb') { |f| f.read }
    end

chuser() click to toggle source

Change the process to a different user

    # File lib/puppet/util.rb, line 81
    def self.chuser
      if group = Puppet[:group]
        begin
          Puppet::Util::SUIDManager.change_group(group, true)
        rescue => detail
          Puppet.warning "could not change to group #{group.inspect}: #{detail}"
          $stderr.puts "could not change to group #{group.inspect}"

          # Don't exit on failed group changes, since it's
          # not fatal
          #exit(74)
        end
      end

      if user = Puppet[:user]
        begin
          Puppet::Util::SUIDManager.change_user(user, true)
        rescue => detail
          $stderr.puts "Could not change to user #{user}: #{detail}"
          exit(74)
        end
      end
    end

classproxy(klass, objmethod, *methods) click to toggle source

Proxy a bunch of methods to another object.

    # File lib/puppet/util.rb, line 131
    def self.classproxy(klass, objmethod, *methods)
      classobj = class << klass; self; end
      methods.each do |method|
        classobj.send(:define_method, method) do |*args|
          obj = self.send(objmethod)

          obj.send(method, *args)
        end
      end
    end

execfail(command, exception) click to toggle source

    # File lib/puppet/util.rb, line 535
    def execfail(command, exception)
      Puppet.deprecation_warning("Puppet::Util.execfail is deprecated; please use Puppet::Util::Execution.execfail")
      Puppet::Util::Execution.execfail(command, exception)
    end

execpipe(command, failonfail = true, &block) click to toggle source

Deprecated methods relating to process execution; these have been moved to Puppet::Util::Execution

    # File lib/puppet/util.rb, line 529
    def execpipe(command, failonfail = true, &block)
      Puppet.deprecation_warning("Puppet::Util.execpipe is deprecated; please use Puppet::Util::Execution.execpipe")
      Puppet::Util::Execution.execpipe(command, failonfail, &block)
    end

execute(*args) click to toggle source

    # File lib/puppet/util.rb, line 541
    def execute(*args)
      Puppet.deprecation_warning("Puppet::Util.execute is deprecated; please use Puppet::Util::Execution.execute")

      Puppet::Util::Execution.execute(*args)
    end

exit_on_fail(message, code = 1) { || ... } click to toggle source

Executes a block of code, wrapped with some special exception handling. Causes the ruby interpreter to

    exit if the block throws an exception.

@api public @param [String] message a message to log if the block fails @param [Integer] code the exit code that the ruby interpreter should return if the block fails @yield

    # File lib/puppet/util.rb, line 503
    def exit_on_fail(message, code = 1)
      yield
    # First, we need to check and see if we are catching a SystemExit error.  These will be raised
    #  when we daemonize/fork, and they do not necessarily indicate a failure case.
    rescue SystemExit => err
      raise err

    # Now we need to catch *any* other kind of exception, because we may be calling third-party
    #  code (e.g. webrick), and we have no idea what they might throw.
    rescue Exception => err
      ## NOTE: when debugging spec failures, these two lines can be very useful
      #puts err.inspect
      #puts Puppet::Util.pretty_backtrace(err.backtrace)
      Puppet.log_exception(err, "Could not #{message}: #{err}")
      Puppet::Util::Log.force_flushqueue()
      exit(code)
    end

logmethods(klass, useself = true) click to toggle source

Create instance methods for each of the log levels. This allows the messages to be a little richer. Most classes will be calling this method.

    # File lib/puppet/util.rb, line 108
    def self.logmethods(klass, useself = true)
      Puppet::Util::Log.eachlevel { |level|
        klass.send(:define_method, level, proc { |args|
          args = args.join(" ") if args.is_a?(Array)
          if useself

            Puppet::Util::Log.create(
              :level => level,
              :source => self,
              :message => args
            )
          else

            Puppet::Util::Log.create(
              :level => level,
              :message => args
            )
          end
        })
      }
    end

memory() click to toggle source

    # File lib/puppet/util.rb, line 327
    def memory
      unless defined?(@pmap)
        @pmap = which('pmap')
      end
      if @pmap
        %x{#{@pmap} #{Process.pid}| grep total}.chomp.sub(/^\s*total\s+/, '').sub(/K$/, '').to_i
      else
        0
      end
    end

path_to_uri(path) click to toggle source

Convert a path to a file URI

    # File lib/puppet/util.rb, line 262
    def path_to_uri(path)
      return unless path

      params = { :scheme => 'file' }

      if Puppet.features.microsoft_windows?
        path = path.gsub(/\/, '/')

        if unc = /^\/\/([^\/]+)(\/[^\/]+)/.match(path)
          params[:host] = unc[1]
          path = unc[2]
        elsif path =~ /^[a-z]:\//i
          path = '/' + path
        end
      end

      params[:path] = URI.escape(path)

      begin
        URI::Generic.build(params)
      rescue => detail
        raise Puppet::Error, "Failed to convert '#{path}' to URI: #{detail}"
      end
    end

pretty_backtrace(backtrace = caller(1)) click to toggle source

utility method to get the current call stack and format it to a human-readable string (which some IDEs/editors will recognize as links to the line numbers in the trace)

    # File lib/puppet/util.rb, line 367
    def self.pretty_backtrace(backtrace = caller(1))
      backtrace.collect do |line|
        _, path, rest = /^(.*):(\d+.*)$/.match(line).to_a
        # If the path doesn't exist - like in one test, and like could happen in
        # the world - we should just tolerate it and carry on. --daniel 2012-09-05
        # Also, if we don't match, just include the whole line.
        if path
          path = Pathname(path).realpath rescue path
          "#{path}:#{rest}"
        else
          line
        end
      end.join("\n")
    end

proxy(klass, objmethod, *methods) click to toggle source

Proxy a bunch of methods to another object.

    # File lib/puppet/util.rb, line 143
    def self.proxy(klass, objmethod, *methods)
      methods.each do |method|
        klass.send(:define_method, method) do |*args|
          obj = self.send(objmethod)

          obj.send(method, *args)
        end
      end
    end

replace_file(file, default_mode) { |tempfile| ... } click to toggle source

Replace a file, securely. This takes a block, and passes it the file handle of a file open for writing. Write the replacement content inside the block and it will safely replace the target file.

This method will make no changes to the target file until the content is successfully written and the block returns without raising an error.

As far as possible the state of the existing file, such as mode, is preserved. This works hard to avoid loss of any metadata, but will result in an inode change for the file.

Arguments: `filename`, `default_mode`

The filename is the file we are going to replace.

The default_mode is the mode to use when the target file doesn’t already exist; if the file is present we copy the existing mode/owner/group values across.

    # File lib/puppet/util.rb, line 400
    def replace_file(file, default_mode, &block)
      raise Puppet::DevError, "replace_file requires a block" unless block_given?

      file     = Pathname(file)
      tempfile = Tempfile.new(file.basename.to_s, file.dirname.to_s)

      file_exists = file.exist?

      # Set properties of the temporary file before we write the content, because
      # Tempfile doesn't promise to be safe from reading by other people, just
      # that it avoids races around creating the file.
      #
      # Our Windows emulation is pretty limited, and so we have to carefully
      # and specifically handle the platform, which has all sorts of magic.
      # So, unlike Unix, we don't pre-prep security; we use the default "quite
      # secure" tempfile permissions instead.  Magic happens later.
      unless Puppet.features.microsoft_windows?
        # Grab the current file mode, and fall back to the defaults.
        stat = file.lstat rescue OpenStruct.new(:mode => default_mode,
                                                :uid  => Process.euid,
                                                :gid  => Process.egid)

        # We only care about the bottom four slots, which make the real mode,
        # and not the rest of the platform stat call fluff and stuff.
        tempfile.chmod(stat.mode & 07777)
        tempfile.chown(stat.uid, stat.gid)
      end

      # OK, now allow the caller to write the content of the file.
      yield tempfile

      # Now, make sure the data (which includes the mode) is safe on disk.
      tempfile.flush
      begin
        tempfile.fsync
      rescue NotImplementedError
        # fsync may not be implemented by Ruby on all platforms, but
        # there is absolutely no recovery path if we detect that.  So, we just
        # ignore the return code.
        #
        # However, don't be fooled: that is accepting that we are running in
        # an unsafe fashion.  If you are porting to a new platform don't stub
        # that out.
      end

      tempfile.close

      if Puppet.features.microsoft_windows?
        # This will appropriately clone the file, but only if the file we are
        # replacing exists.  Which is kind of annoying; thanks Microsoft.
        #
        # So, to avoid getting into an infinite loop we will retry once if the
        # file doesn't exist, but only the once...
        have_retried = false

        begin
          # Yes, the arguments are reversed compared to the rename in the rest
          # of the world.
          Puppet::Util::Windows::File.replace_file(file, tempfile.path)
        rescue Puppet::Util::Windows::Error => e
          # This might race, but there are enough possible cases that there
          # isn't a good, solid "better" way to do this, and the next call
          # should fail in the same way anyhow.
          raise if have_retried or File.exist?(file)
          have_retried = true

          # OK, so, we can't replace a file that doesn't exist, so let us put
          # one in place and set the permissions.  Then we can retry and the
          # magic makes this all work.
          #
          # This is the least-worst option for handling Windows, as far as we
          # can determine.
          File.open(file, 'a') do |fh|
            # this space deliberately left empty for auto-close behaviour,
            # append mode, and not actually changing any of the content.
          end

          # Set the permissions to what we want.
          Puppet::Util::Windows::Security.set_mode(default_mode, file.to_s)

          # ...and finally retry the operation.
          retry
        end
      else
        File.rename(tempfile.path, file)
      end

      # Ideally, we would now fsync the directory as well, but Ruby doesn't
      # have support for that, and it doesn't matter /that/ much...

      # Return something true, and possibly useful.
      file
    end

safe_posix_fork(stdin=$stdin, stdout=$stdout, stderr=$stderr, &block) click to toggle source

    # File lib/puppet/util.rb, line 306
    def safe_posix_fork(stdin=$stdin, stdout=$stdout, stderr=$stderr, &block)
      child_pid = Kernel.fork do
        $stdin.reopen(stdin)
        $stdout.reopen(stdout)
        $stderr.reopen(stderr)

        3.upto(256){|fd| IO::new(fd).close rescue nil}

        block.call if block
      end
      child_pid
    end

symbolizehash(hash) click to toggle source

    # File lib/puppet/util.rb, line 338
    def symbolizehash(hash)
      newhash = {}
      hash.each do |name, val|
        name = name.intern if name.respond_to? :intern
        newhash[name] = val
      end
      newhash
    end

synchronize_on(x,type) { || ... } click to toggle source

    # File lib/puppet/util.rb, line 66
    def self.synchronize_on(x,type)
      sync_object,users = 0,1
      begin
        @@sync_objects.synchronize {
          (@@sync_objects[x] ||= [Sync.new,0])[users] += 1
        }
        @@sync_objects[x][sync_object].synchronize(type) { yield }
      ensure
        @@sync_objects.synchronize {
          @@sync_objects.delete(x) unless (@@sync_objects[x][users] -= 1) > 0
        }
      end
    end

thinmark() { || ... } click to toggle source

Just benchmark, with no logging.

    # File lib/puppet/util.rb, line 349
    def thinmark
      seconds = Benchmark.realtime {
        yield
      }

      seconds
    end

uri_to_path(uri) click to toggle source

Get the path component of a URI

    # File lib/puppet/util.rb, line 289
    def uri_to_path(uri)
      return unless uri.is_a?(URI)

      path = URI.unescape(uri.path)

      if Puppet.features.microsoft_windows? and uri.scheme == 'file'
        if uri.host
          path = "//#{uri.host}" + path # UNC
        else
          path.sub!(/^\//, '')
        end
      end

      path
    end

which(bin) click to toggle source

Resolve a path for an executable to the absolute path. This tries to behave in the same manner as the unix `which` command and uses the `PATH` environment variable.

@api public @param bin [String] the name of the executable to find. @return [String] the absolute path to the found executable.

    # File lib/puppet/util.rb, line 195
    def which(bin)
      if absolute_path?(bin)
        return bin if FileTest.file? bin and FileTest.executable? bin
      else
        ENV['PATH'].split(File::PATH_SEPARATOR).each do |dir|
          begin
            dest = File.expand_path(File.join(dir, bin))
          rescue ArgumentError => e
            # if the user's PATH contains a literal tilde (~) character and HOME is not set, we may get
            # an ArgumentError here.  Let's check to see if that is the case; if not, re-raise whatever error
            # was thrown.
            if e.to_s =~ /HOME/ and (ENV['HOME'].nil? || ENV['HOME'] == "")
              # if we get here they have a tilde in their PATH.  We'll issue a single warning about this and then
              # ignore this path element and carry on with our lives.
              Puppet::Util::Warnings.warnonce("PATH contains a ~ character, and HOME is not set; ignoring PATH element '#{dir}'.")
            elsif e.to_s =~ /doesn't exist|can't find user/
              # ...otherwise, we just skip the non-existent entry, and do nothing.
              Puppet::Util::Warnings.warnonce("Couldn't expand PATH containing a ~ character; ignoring PATH element '#{dir}'.")
            else
              raise
            end
          else
            if Puppet.features.microsoft_windows? && File.extname(dest).empty?
              exts = ENV['PATHEXT']
              exts = exts ? exts.split(File::PATH_SEPARATOR) : %w[.COM .EXE .BAT .CMD]
              exts.each do |ext|
                destext = File.expand_path(dest + ext)
                return destext if FileTest.file? destext and FileTest.executable? destext
              end
            end
            return dest if FileTest.file? dest and FileTest.executable? dest
          end
        end
      end
      nil
    end

withenv(hash) { || ... } click to toggle source

Run some code with a specific environment. Resets the environment back to what it was at the end of the code.

    # File lib/puppet/util.rb, line 39
    def self.withenv(hash)
      saved = ENV.to_hash
      hash.each do |name, val|
        ENV[name.to_s] = val
      end

      yield
    ensure
      ENV.clear
      saved.each do |name, val|
        ENV[name] = val
      end
    end

withumask(mask) { || ... } click to toggle source

Execute a given chunk of code with a new umask.

    # File lib/puppet/util.rb, line 55
    def self.withumask(mask)
      cur = File.umask(mask)

      begin
        yield
      ensure
        File.umask(cur)
      end
    end

### Public Instance Methods

threadlock(resource, type = Sync::EX) { || ... } click to toggle source

Create an exclusive lock.

    # File lib/puppet/util.rb, line 321
    def threadlock(resource, type = Sync::EX)
      Puppet::Util.synchronize_on(resource,type) { yield }
    end