linux_stat 0.1.1 → 0.2.0

data/lib/linux_stat/bios.rb

@@ -1,6 +1,9 @@
 module LinuxStat
 	module BIOS
 		class << self
+			# Returns the model of the BIOS.
+			# If the information is not available it will return a frozen empty string.
+			# The output is also cached ; as changing the value in runtime is unexpected.
 			def model
 				# Cached ; as changing the value in runtime is unexpected
 				@@model ||= if File.readable?('/sys/devices/virtual/dmi/id/product_name')
@@ -12,6 +15,9 @@ module LinuxStat
 				end
 			end
 
+			# Returns the vendor of the BIOS.
+			# If the information is not available it will return a frozen empty string.
+			# The output is also cached ; as changing the value in runtime is unexpected.
 			def vendor
 				# Cached ; as changing the value in runtime is unexpected
 				@@vendor ||= if File.readable?('/sys/devices/virtual/dmi/id/bios_vendor')
@@ -21,8 +27,10 @@ module LinuxStat
 				end
 			end
 
+			# Returns the version of the BIOS.
+			# If the information is not available it will return a frozen empty string.
+			# The output is also cached ; as changing the value in runtime is unexpected.
 			def version
-				# Cached ; as changing the value in runtime is unexpected
 				@@version ||= if File.readable?('/sys/devices/virtual/dmi/id/bios_version')
 					IO.read('/sys/devices/virtual/dmi/id/bios_version').tap(&:strip!)
 				else
@@ -30,8 +38,10 @@ module LinuxStat
 				end
 			end
 
+			# Returns the date of the BIOS.
+			# If the information is not available it will return a frozen empty string.
+			# The output is also cached ; as changing the value in runtime is unexpected.
 			def date
-				# Cached ; as changing the value in runtime is unexpected
 				@@date ||= if File.readable?('/sys/devices/virtual/dmi/id/bios_date')
 					IO.read('/sys/devices/virtual/dmi/id/bios_date').tap(&:strip!)
 				else

data/lib/linux_stat/cpu.rb

@@ -1,6 +1,15 @@
 module LinuxStat
 	module CPU
 		class << self
+			# Returns the cpu usage of all threads.
+			#
+			# The first one is aggregated CPU usage reported by the Linux kernel.
+			# And the consecutive ones are the real core usages.
+			#
+			# On a system with 4 threads, the output will be like::
+			# {0=>84.38, 1=>100.0, 2=>50.0, 3=>87.5, 4=>87.5}
+			#
+			# If the information is not available, it will return an empty Hash
 			def stat(sleep = 0.075)
 				return {} unless stat?
 
@@ -21,35 +30,56 @@ module LinuxStat
 				end
 			end
 
+			# Returns the total cpu usage.
+			# It's like running LinuxStat::CPU.stat[0] but it's much more efficient and calculates just the aggregated usage which is available at the top of the /proc/stat file.
+			#
+			# If the information is not available, it will return nil.
+			def total_usage(sleep = 0.075)
+				return nil unless stat?
+
+				data = IO.foreach('/proc/stat').first.split.tap(&:shift).map!(&:to_f)
+				sleep(sleep)
+				data2 = IO.foreach('/proc/stat').first.split.tap(&:shift).map!(&:to_f)
+
+				user, nice, sys, idle, iowait, irq, softirq, steal = *data
+				user2, nice2, sys2, idle2, iowait2, irq2, softirq2, steal2 = *data2
+
+				idle_then, idle_now  = idle + iowait, idle2 + iowait2
+				totald = idle_now.+(user2 + nice2 + sys2 + irq2 + softirq2 + steal2) - idle_then.+(user + nice + sys + irq + softirq + steal)
+				totald.-(idle_now - idle_then).fdiv(totald).*(100).round(2).abs
+			end
+
+			# Returns the total number of CPU threads.
+			# If the information isn't available, it will return 0.
 			def count
 				# CPU count can change during the program runtime
 				cpuinfo.count { |x| x.start_with?('processor') }
 			end
 
+			# Returns the model of processor.
+			# If the information isn't available, it will return en empty string.
+			# The output is also cached ; as changing the value in runtime is unexpected.
 			def model
-				# Cached ; as changing the value in runtime is unexpected ; nobody is going
-				# to add/remove CPUs during program runtime
 				@@name ||= cpuinfo.find { |x| x.start_with?('model name') }.to_s.split(?:)[-1].to_s.strip
 			end
 
-			# Returns an array with current core frequencies corresponding to the usages
+			# Returns an array with current core frequencies corresponding to the usages.
+			# If the information isn't available, it will return an empty array.
 			def cur_freq
-				# Cached ; as changing the value in runtime is unexpected ; nobody is going
-				# to add/remove CPUs during program runtime
-
 				@@cpu_freqs ||= Dir["/sys/devices/system/cpu/cpu[0-9]*/cpufreq/scaling_cur_freq"]
 				@@cpu_freqs.map { |x| IO.read(x).to_i }
 			end
 
-			# Returns an array with max core frequencies corresponding to the usages
+			# Returns an array with max core frequencies corresponding to the usages.
+			# If the information isn't available, it will return an empty array.
 			def max_freq
-				# Cached ; as changing the value in runtime is unexpected ; nobody is going
-				# to add/remove CPUs during program runtime
-
 				@@max_freqs ||= Dir["/sys/devices/system/cpu/cpu[0-9]*/cpufreq/scaling_max_freq"]
 				@@max_freqs.map { |x| IO.read(x).to_i }
 			end
 
+			alias usages stat
+			alias usage total_usage
+
 			private
 			def cpuinfo
 				File.readable?('/proc/cpuinfo') ? IO.readlines('/proc/cpuinfo') : []

data/lib/linux_stat/kernel.rb

@@ -1,37 +1,147 @@
 module LinuxStat
 	module Kernel
 		class << self
+			# Returns the Linux Kernel version.
+			# If the information isn't available, it will return a frozen empty string.
+			# The output is also cached ; as changing the value in runtime is unexpected.
 			def version
-				return @@version ||= ''.freeze if string.empty?
-				@@version ||= string.split[2]
+				return ''.freeze if string.empty?
+				@@version ||= splitted[2]
 			end
 
+			# Returns the name of the user who built the kernel using KBUILD_FLAGS.
+			# If the information isn't available, it will return a frozen empty string.
+			# The output is also cached ; as changing the value in runtime is unexpected.
+			def build_user
+				@@build_user ||= string.split(/(\(.+\))/).each(&:strip!)
+					.reject(&:empty?).find { |x| x[/^\(.+\)$/] }.to_s
+					.split[0].to_s[1..-2].to_s.freeze
+			end
+
+			# Returns the compiler used to compile the Linux Kernel.
+			# If the information isn't available, it will return a frozen empty string.
+			# The output is also cached ; as changing the value in runtime is unexpected.
 			def compiler
-				return @@compiler ||= ''.freeze if string.empty?
+				return ''.freeze if string.empty?
+
+				@@compiler ||= string.split(/(\(.+\))/).each(&:strip!)
+					.reject(&:empty?)
+					.find { |x| x[/^\(.+\)$/] }.to_s
+					.split.find { |x| !x[/^(.+@.+)$/] }.to_s[/\w+/].to_s.freeze
 
-				@@compiler ||= case string.split[4].to_s
+				@@compiler_val ||= case @@compiler
 					when /gcc/i then [:gcc ]
 					when /clang/i then [:clang]
 					when /icc/i then [:icc]
-				end << string[/\(.*\)/].split.drop(1).find { |x| x[/^\d.*\d/] }[/^\d.*\d/]
+					else [@@compiler &.to_sym]
+				end << compiler_version
+			end
+
+			# Returns the compiler version used to compile the Linux Kernel.
+			# If the information isn't available, it will return a frozen empty string.
+			# The output is also cached ; as changing the value in runtime is unexpected.
+			def compiler_version
+				@@compiler_version ||= string.split(/(\(.+?\))/).each(&:strip!)
+					.reject(&:empty?)[2..4].to_a
+					.find { |x| x[/[\d.]+/] }.to_s[/[\d.]+/].to_s.freeze
 			end
 
+			# Returns the time when the kernel was compiled.
+			# The return value is a Time object.
+			# If the information isn't available, it will return nil
+			#
+			# The time will be searched in specific order.
+			# It will match any date matching any of these formats:
+			# 1. %b %d %H:%M:%S %z %Y
+			# 2. %d %b %Y %H:%M:%S %z
+			# 3. %Y-%m-%d
+			# Most kernels have date in them in this format.
+			#
+			# Do note that Ruby sometimes fails to work with timezones like BST for example.
+			# In such case, the timezone is unrealiable and often returns the local timezone.
+			# You have to use regexp yourself to get the proper zone.
+			# Use LinuxStat::Kernel.build_date_string to get the original string if you need that.
+			#
+			# The output is also cached ; as changing the value in runtime is unexpected.
 			def build_date
-				return @@time ||= Time.new(0) if string.empty?
+				return nil if splitted.empty?
 
 				@@time ||= begin
-					require 'time'
-					Time.strptime(string.split[16..-1].join(' '), "%d %b %Y %H:%M:%S %z")
-				rescue StandardError
-					Time.new(0)
+					require 'time' unless Time.respond_to?(:strptime)
+
+					splitted.each_cons(5).map do |x|
+						joined = x.each(&:strip!).join(?\s.freeze)
+
+						# Match 21 Oct 2020 01:11:20 +0000
+						if joined[/^\d{2}\s\w{3}\s\d{4}\s\d{2}:\d{2}:\d{2}\s\+\d*$/]
+							Time.strptime(joined, '%d %b %Y %H:%M:%S %Z') rescue nil
+
+						# Match Aug 25 17:23:54 UTC 2020
+						elsif joined[/^\w{3}\s\d{2}\s\d{2}:\d{2}:\d{2}\s\w+\s\d*$/]
+							Time.strptime(joined, '%b %d %H:%M:%S %z %Y') rescue nil
+
+						# Match 2017-09-19
+						elsif joined[/\d{4}-\d{2}-\d{2}/]
+							Time.strptime(joined[/\d{4}-\d{2}-\d{2}/] + " +00:00", '%Y-%m-%d %z') rescue nil
+
+						else
+							nil
+						end
+					end.tap(&:compact!)[0]
 				end
 			end
 
+			# Returns the time when the kernel was compiled.
+			# The return value is a String.
+			# If the information isn't available, it will return nil
+			#
+			# The time will be searched in specific order.
+			# It will match any date matching any of these formats:
+			# 1. %b %d %H:%M:%S %z %Y
+			# 2. %d %b %Y %H:%M:%S %z
+			# 3. %Y-%m-%d
+			# Most kernels have date in them in this format.
+			#
+			# Do note that Ruby sometimes fails to work with timezones like BST for example.
+			# In such case, the timezone is unrealiable and often returns the local timezone.
+			# You have to use regexp yourself to get the proper zone.
+			# Use LinuxStat::Kernel.build_date_string to get the original string if you need that.
+			#
+			# The output is also cached ; as changing the value in runtime is unexpected.
+			def build_date_string
+				return nil if splitted.empty?
+
+				@@time2 ||= begin
+					require 'time' unless Time.respond_to?(:strptime)
+
+					splitted.each_cons(5).map do |x|
+						joined = x.each(&:strip!).join(?\s.freeze)
+
+						# Match 21 Oct 2020 01:11:20 +0000
+						if (joined[/^\d{2}\s\w{3}\s\d{4}\s\d{2}:\d{2}:\d{2}\s\+\d*$/] && (Time.strptime(joined, '%d %b %Y %H:%M:%S %Z') rescue nil)) ||
+
+						# Match Aug 25 17:23:54 UTC 2020
+						(joined[/^\w{3}\s\d{2}\s\d{2}:\d{2}:\d{2}\s\w+\s\d*$/] && (Time.strptime(joined, '%b %d %H:%M:%S %z %Y') rescue nil)) ||
+
+						# Match 2017-09-19
+						(joined[/\d{4}-\d{2}-\d{2}/] && (Time.strptime(joined[/\d{4}-\d{2}-\d{2}/] + " +00:00", '%Y-%m-%d %z') rescue nil))
+							joined
+						else
+							nil
+						end
+					end.tap(&:compact!)[0]
+				end
+			end
+
+			# Reads maximum 1024 bytes from /proc/version and returns the string.
+			# The output is also cached ; as changing the value in runtime is unexpected.
 			def string
-				# Cached ; as changing the value in runtime is unexpected
-				# Hotfix update can be problem, but it's rare and might not
-				# affect the version string during program runtime.
-				@@string ||= File.readable?('/proc/version') ? IO.read('/proc/version').tap(&:strip!) : ''
+				@@string ||= File.readable?('/proc/version') ? IO.read('/proc/version', 1024).tap(&:strip!) : ''
+			end
+
+			private
+			def splitted
+				@@string_splitted ||= string.split
 			end
 		end
 	end

data/lib/linux_stat/memory.rb

@@ -1,6 +1,11 @@
 module LinuxStat
 	module Memory
 		class << self
+			# Returns the memory details reported by /proc/meminfo. In this format:
+			# {:total=>3836264, :used=>3097952, :available=>738312, :percent_used=>80.75, :percent_available=>19.25}
+			#
+			# The value is in Kilobyte.
+			# If the statistics is not available, it will return an empty Hash.
 			def stat
 				return {} unless meminfo?
 
@@ -24,31 +29,44 @@ module LinuxStat
 				}
 			end
 
+			# Returns the total memory details reported by /proc/meminfo.
+			# The value is in Kilobyte.
+			# It retuns an Integer but if the info is not available, it will return nil.
 			def total
-				return 0 unless meminfo?
+				return nil unless meminfo?
 				IO.foreach('/proc/meminfo').first.split[1].to_i
 			end
 
+			# Returns the total memory details reported by /proc/meminfo.
+			# The value is in Kilobyte.
+			# It retuns an Integer but if the info is not available, it will return nil
 			def available
-				return 0 unless meminfo?
+				return nil unless meminfo?
 				IO.foreach('/proc/meminfo').first(3)[-1].split[1].to_i
 			end
 
+			# Returns the amount of memory used reported by /proc/meminfo.
+			# The value is in Kilobyte.
+			# It retuns an Integer but if the info is not available, it will return nil.
 			def used
-				return 0 unless meminfo?
+				return nil unless meminfo?
 				memory = IO.foreach('/proc/meminfo').first(3)
 				memory[0].split[1].to_i - memory[2].split[1].to_i
 			end
 
+			# Returns the percentage of memory used reported by /proc/meminfo.
+			# It retuns an Integer but if the info is not available, it will return nil
 			def percent_used
-				return 0.0 unless meminfo?
+				return nil unless meminfo?
 				memory = IO.foreach('/proc/meminfo').first(3)
 				total = memory[0].split[1].to_i
 				total.-(memory[2].split[1].to_i).*(100).fdiv(total).round(2)
 			end
 
+			# Returns the percentage of memory used reported by /proc/meminfo.
+			# It retuns an Integer but if the info is not available,  it will return nil
 			def percent_available
-				return 0.0 unless meminfo?
+				return nil unless meminfo?
 				memory = IO.foreach('/proc/meminfo').first(3)
 				memory[2].split[1].to_i.*(100).fdiv(memory[0].split[1].to_i).round(2)
 			end

data/lib/linux_stat/net.rb

@@ -1,10 +1,12 @@
 module LinuxStat
 	module Net
 		class << self
+			# Returns the local IP address of the system as a String.
+			# If the information isn't available, it will a frozen empty string.
 			def ipv4_private
 				require 'socket'
 				ip = Socket.ip_address_list.find(&:ipv4_private?)
-				ip ? ip.ip? ? ip.ip_unpack[0].freeze : '' : ''
+				ip ? ip.ip? ? ip.ip_unpack[0].freeze : ''.freeze : ''.freeze
 			end
 		end
 	end

data/lib/linux_stat/os.rb

@@ -1,18 +1,83 @@
 module LinuxStat
 	module OS
 		class << self
+			# Reads /etc/os-release and returns a Hash. For example:
+			# {:NAME=>"Arch Linux", :PRETTY_NAME=>"Arch Linux", :ID=>"arch", :BUILD_ID=>"rolling", :ANSI_COLOR=>"38;2;23;147;209", :HOME_URL=>"https://www.archlinux.org/", :DOCUMENTATION_URL=>"https://wiki.archlinux.org/", :SUPPORT_URL=>"https://bbs.archlinux.org/", :BUG_REPORT_URL=>"https://bugs.archlinux.org/", :LOGO=>"archlinux"}
+			#
+			# If the info isn't available, it will return an empty Hash.
+			#
+			# The amount of data read is 4096 bytes. Any more than that will result in truncated output.
+			#
+			# The information is also cached, and once loaded, won't change in runtime. Because changing the /etc/lsb-release
+			# isn't expected in runtime.
 			def os_release
 				# Cached ; as changing the value in runtime is unexpected
 				@@os_release ||= File.readable?('/etc/os-release') ? release('/etc/os-release') : {}
 			end
 
+			# Reads /etc/lsb-release and returns a Hash. For example:
+			# {:LSB_VERSION=>"1.4", :DISTRIB_ID=>"Arch", :DISTRIB_RELEASE=>"rolling", :DISTRIB_DESCRIPTION=>"Arch Linux"}
+			#
+			# If the info isn't available, it will return an empty Hash.
+			#
+			# The amount of data read is 4096 bytes. Any more than that will result in truncated output.
+			#
+			# The information is also cached, and once loaded, won't change in runtime. Because changing the /etc/lsb-release
+			# isn't expected in runtime.
 			def lsb_release
 				# Cached ; as changing the value in runtime is unexpected
 				@@lsb_release ||= File.readable?('/etc/lsb-release') ? release('/etc/lsb-release') : {}
 			end
 
+			# Reads /etc/lsb-release or /etc/os-release tries to get information about the distribution.
+			# If the information isn't available, it will read and return /etc/issue.
+			# The return type is String.
+			# If none of the info is available, it will return an empty frozen String.
+			def distribution
+				@@distribution ||= if os_release.key?(:NAME)
+					os_release[:NAME]
+				else
+					v = lsb_release
+
+					if v.key?(:DISTRIB_DESCRIPTION)
+						v[:DISTRIB_DESCRIPTION]
+					elsif v.key?(:DISTRIB_ID)
+						v[:DISTRIB_ID]
+					elsif File.readable?('/etc/issue')
+						IO.read('/etc/issue').strip
+					else
+						'Unknown'.freeze
+					end
+				end
+			end
+
+			# Reads /etc/hostname and returns the hostname.
+			# The return type is String.
+			# If the info info isn't available, it will return 'localhost'.
+			def hostname
+				@@hostname ||= if File.exist?('/etc/hostname')
+					IO.read('/etc/hostname').strip
+				else
+					'localhost'
+				end
+			end
+
+			# Reads ruby configuration and tries to guess if the system is 32 bit or 64 bit.
+			# The return type is Integer.
+			def bits
+				@@bits ||= if RbConfig::CONFIG['host_cpu'].end_with?('64') || RUBY_PLATFORM[/x86_64/]
+					64
+				else
+					32
+				end
+			end
+
+			# Reads /proc/uptime and returns the system uptime:
+			# {:hour=>10, :minute=>34, :second=>12.59}
+			#
+			# If the stat isn't available, an empty hash is returned.
 			def uptime
-				raise StatUnavailable, 'Cannot read /proc/uptime' unless uptime_readable?
+				return {} unless uptime_readable?
 
 				uptime = IO.read('/proc/uptime').to_f
 				uptime_i = uptime.to_i
@@ -30,7 +95,7 @@ module LinuxStat
 
 			private
 			def release(file)
-				IO.readlines(file).reduce({}) { |h, x|
+				IO.readlines(file, 4096).reduce({}) { |h, x|
 					x.strip!
 					next h if x.empty?
 
@@ -39,8 +104,10 @@ module LinuxStat
 					key = splitted[0].to_s.strip
 					value = splitted[1..-1].join(?=).to_s.strip
 
-					dumped = value[0] == ?" && value[-1] == ?"
-					h.merge!( key.to_sym => dumped ? value.undump : value )
+					value[0] = '' if value[0] == ?"
+					value[-1] = '' if value[-1] == ?"
+
+					h.merge!( key.to_sym => value )
 				}
 			end