{"id":23385541,"url":"https://github.com/souravgoswami/linux_stat","last_synced_at":"2025-06-20T14:35:56.179Z","repository":{"id":38251060,"uuid":"315047835","full_name":"Souravgoswami/linux_stat","owner":"Souravgoswami","description":"Linux only, efficient system utilization reporting and system monitoring gem","archived":false,"fork":false,"pushed_at":"2024-10-26T08:06:31.000Z","size":8465,"stargazers_count":17,"open_issues_count":1,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-18T10:54:04.092Z","etag":null,"topics":["battery","bios","cpu","filesystem","kernel","linux","linux-stat","linux-stats","memory","mount","net","os","process","rails-gem","ruby","ruby-gem","statvfs","swap","unistd-h","utsname"],"latest_commit_sha":null,"homepage":"https://souravgoswami.github.io/linux_stat","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Souravgoswami.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-11-22T13:46:47.000Z","updated_at":"2025-06-01T18:06:36.000Z","dependencies_parsed_at":"2023-02-10T08:30:31.058Z","dependency_job_id":"514db457-ba9d-4fdb-bce9-36b60aa93f5d","html_url":"https://github.com/Souravgoswami/linux_stat","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Souravgoswami/linux_stat","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Souravgoswami%2Flinux_stat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Souravgoswami%2Flinux_stat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Souravgoswami%2Flinux_stat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Souravgoswami%2Flinux_stat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Souravgoswami","download_url":"https://codeload.github.com/Souravgoswami/linux_stat/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Souravgoswami%2Flinux_stat/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260962749,"owners_count":23089475,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["battery","bios","cpu","filesystem","kernel","linux","linux-stat","linux-stats","memory","mount","net","os","process","rails-gem","ruby","ruby-gem","statvfs","swap","unistd-h","utsname"],"created_at":"2024-12-22T00:19:19.939Z","updated_at":"2025-06-20T14:35:51.164Z","avatar_url":"https://github.com/Souravgoswami.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LinuxStat [![Ruby Gem](https://badge.fury.io/rb/linux_stat.svg)](https://rubygems.org/gems/linux_stat) ![Workflow Status](https://github.com/souravgoswami/linux_stat/workflows/LinuxStat%20Test/badge.svg)\n\n---\n\n![logo](https://raw.githubusercontent.com/Souravgoswami/linux_stat/master/images/logo.jpg)\n\nFor reading the eyecandy HTML version, visit [linux_stat](https://souravgoswami.github.io/linux_stat/).\n\nLinuxStat lets you read status of a Linux system. It can show you cpu stats and usages, memory stats and usages, swap stats and usages, battery usage, bios info,  kernel details, local ip, os details and parse os-release + lsb-release, etc.\n\nIt only works on Linux, and detecting the OS is upto the user of this gem.\n\n---\n\n| Table of Contents |\n|:---|\n| [Runtime Dependencies](https://github.com/Souravgoswami/linux_stat#runtime-dependencies) |\n| [Build Dependencies](https://github.com/Souravgoswami/linux_stat#build-dependencies) |\n| [Optional Runtime Dependencies](https://github.com/Souravgoswami/linux_stat#optional-runtime-dependencies) |\n| [Installation](https://github.com/Souravgoswami/linux_stat#installation) |\n| [Usage](https://github.com/Souravgoswami/linux_stat#usage) |\n| [Notes](https://github.com/Souravgoswami/linux_stat#notes) |\n| [Return Types](https://github.com/Souravgoswami/linux_stat#return-types) |\n| [Ruby On Rails](https://github.com/Souravgoswami/linux_stat#ruby-on-rails) |\n| [Android](https://github.com/Souravgoswami/linux_stat#android) |\n| [Cloning this Repo](https://github.com/Souravgoswami/linux_stat#cloning-this-repo) |\n| [Development](https://github.com/Souravgoswami/linux_stat#development) |\n| [Testing](https://github.com/Souravgoswami/linux_stat#testing) |\n| [Contributing](https://github.com/Souravgoswami/linux_stat#contributing) |\n| [License](https://github.com/Souravgoswami/linux_stat#license) |\n| [Languages](https://github.com/Souravgoswami/linux_stat#languages) |\n\n---\n\n## Runtime Dependencies:\n\n1. Kernel: Any Linux distribution with Kernel 3.14+.\n2. Ruby: Ruby 2.3.0 and above.\n\n## Build Dependencies:\n#### You need to have the C compiler installed to be able to compile the C extensions.\n\n+ On Arch Linux / Manjaro / Archlabs / Other Arch Based Distributions\n```\n# pacman -S gcc make ruby\n```\n\n+ On Debian / Ubuntu / Linux Mint / Pop!_OS / Raspberry Pi OS / Other Debian Based Distributions\n```\n# apt install gcc build-essential ruby ruby-dev build-essential\n```\n\n+ Gentoo / Gentoo Based Distributions\n```\n# emerge --ask dev-lang/ruby\n```\n\n+ Fedora / AmazonLinux* / CentOS* / Other RedHat Based Distributions\n```\n# yum install gcc ruby-devel ruby make\n```\n\nYou can run linux_stat on *AmazonLinux and *CentOS if you have Ruby 2.3.0+.\n\n+ OpenSUSE\n```\n# zypper install gcc ruby ruby-devel make\n```\n\n+ You can remove the above packages once the gem is installed.\n\n---\n\n## Optional Runtime Dependencies\n\nYou need hwdata to decode vendor and product ids if you use LinuxStat::USB and/or LinuxStat::PCI\n\nYou can install hwdata simply.\n\n+ Arch:\n\n```\n# pacman -S hwids\n```\n\n+ Debian based systems:\n\n```\n# apt install hwdata\n```\n\n+ Gentoo / Gentoo Based Distributions\n```\n# emerge --ask sys-apps/hwids\n```\n\n+ Fedora / Amazon Linux / CentOS\n```\n# yum install hwdata\n```\n\n+ OpenSUSE\n```\nzypper install hwdata\n```\n\nBut without hwdata, it won't show such information.\n\nYou can also point to a downloaded copy of hwdata (pci.ids / usb.ids) file.\n\nFollow [Note 7](https://github.com/Souravgoswami/linux_stat#note-7-hwdata) below for more information on that.\n\n---\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'linux_stat'\n```\n\nAnd then execute:\n\n```\n$ bundle install\n```\n\nOr install it yourself as:\n\n```\n$ gem install linux_stat\n```\n\n## Usage\n\nFollowing are the LinuxStat modules and module functions in a table.\nUsages.md is generated by `linuxstat.rb -md` command, which is available after the installation.\n\nFor ease of use, LinuxStat is also assigned to the LS constant.\nSo LinuxStat::USB can be replaced with LS::USB for example.\n\n| LinuxStat Module | Description |\n|:---|:---|\n| [LinuxStat::BIOS](https://github.com/Souravgoswami/linux_stat/blob/master/Usages.md#linuxstatbios) | System's BIOS related informaion |\n| [LinuxStat::Battery](https://github.com/Souravgoswami/linux_stat/blob/master/Usages.md#linuxstatbattery) | System's first Battery realted information |\n| [LinuxStat::CPU](https://github.com/Souravgoswami/linux_stat/blob/master/Usages.md#linuxstatcpu) | System's CPU usage and other related information |\n| [LinuxStat::FS](https://github.com/Souravgoswami/linux_stat/blob/master/Usages.md#linuxstatfs) | System's file system related information. It's used by Filesystem module. |\n| [LinuxStat::Filesystem](https://github.com/Souravgoswami/linux_stat/blob/master/Usages.md#linuxstatfilesystem) | System's file system usage and other related information |\n| [LinuxStat::FTW](https://github.com/Souravgoswami/linux_stat/blob/master/Usages.md#linuxstatftw) | File Tree Walk: Walks through a file and gives you data related to it's own and sub files and directories |\n| [LinuxStat::Kernel](https://github.com/Souravgoswami/linux_stat/blob/master/Usages.md#linuxstatkernel) | System's kernel related information |\n| [LinuxStat::Memory](https://github.com/Souravgoswami/linux_stat/blob/master/Usages.md#linuxstatmemory) | System's memory (RAM) usage and other related information |\n| [LinuxStat::Mounts](https://github.com/Souravgoswami/linux_stat/blob/master/Usages.md#linuxstatmounts) | System's mount point related information |\n| [LinuxStat::Net](https://github.com/Souravgoswami/linux_stat/blob/master/Usages.md#linuxstatnet) | System's internet usage and other information |\n| [LinuxStat::OS](https://github.com/Souravgoswami/linux_stat/blob/master/Usages.md#linuxstatos) | System's OS related information and parse release files |\n| [LinuxStat::PCI](https://github.com/Souravgoswami/linux_stat/blob/master/Usages.md#linuxstatpci) | System's PCI device related information (optional parsing of hwdata) |\n| [LinuxStat::PrettifyBytes](https://github.com/Souravgoswami/linux_stat/blob/master/Usages.md#linuxstatprettifybytes) | Convert bytes into human readable format (kB, kiB, etc.) |\n| [LinuxStat::ProcFS](https://github.com/Souravgoswami/linux_stat/blob/master/Usages.md#linuxstatprocfs) | Read proc file system in C for faster access. Used accross |\n| [LinuxStat::Process](https://github.com/Souravgoswami/linux_stat/blob/master/Usages.md#linuxstatprocess) | System's processes and related information |\n| [LinuxStat::ProcessInfo](https://github.com/Souravgoswami/linux_stat/blob/master/Usages.md#linuxstatprocessinfo)   | System's single process CPU, memory usages, CPU time, etc. info |\n| [LinuxStat::Swap](https://github.com/Souravgoswami/linux_stat/blob/master/Usages.md#linuxstatswap) | System's swap related information |\n| [LinuxStat::Sysconf](https://github.com/Souravgoswami/linux_stat/blob/master/Usages.md#linuxstatsysconf) | Used by other LinuxStat modules, provides various system details like pagesize, max children, open files, etc |\n| [LinuxStat::Sysinfo](https://github.com/Souravgoswami/linux_stat/blob/master/Usages.md#linuxstatsysinfo) | Used by other LinuxStat modules, faster access to information like totalram, freeram, totalhigh, load average, etc. |\n| [LinuxStat::Thermal](https://github.com/Souravgoswami/linux_stat/blob/master/Usages.md#linuxstatthermal) | System's thermal status, fan related info, sensor count, fan count, etc. |\n| [LinuxStat::USB](https://github.com/Souravgoswami/linux_stat/blob/master/Usages.md#linuxstatusb) | System's USB device related information and other counts (optional parsing of hwdata) |\n| [LinuxStat::Uname](https://github.com/Souravgoswami/linux_stat/blob/master/Usages.md#linuxstatuname) | Used by other LinuxStat modules, System's Uname information in C, that's also provided by the `uname` command. |\n| [LinuxStat::User](https://github.com/Souravgoswami/linux_stat/blob/master/Usages.md#linuxstatuser) | Systems' various user related information, provides current user name, home directory, etc. |\n\n---\n\n# Notes\n\n## Note 1: CPU usage, and Net usage\nTo calculate the current usage, we need to get two usages at a given interval, and subtract the 2nd from the 1st.\nFor example, if the current download (`LinuxStat::Net.total_bytes_received`) is 1000 bytes, and if 0.1 seconds ago, it was 100 bytes, that means 900 bytes was received in 0.1 seconds.\nThat means the current speed is 9000 bytes/s or 9 kB/s.\n\nWithout the polling, it's not really possible to calculate the current usage. Although the total usage can be calculated.\nA system monitor does that, too...\n\nThus these methods requires a polling interval:\n\n1. LinuxStat::CPU.stat, usage, total_usage, usage.\n2. LinuxStat::ProcessInfo.cpu_usage, cpu_stat.\n3. LinuxStat::Net.usage, current_usage.\n\nThey sleep for a given interval and then differentiate between the data.\n\nFor more info look at the ri documentation for the above methods.\n\nThese methods can slow down your application a bit unless you implement them in a thread.\n\nOther methods doesn't have the sleep implemented, and they just works under a millisecond.\n\nFor example:\n\n```\nLinuxStat::CPU.stat(0.1)\n=\u003e {0=\u003e7.69, 1=\u003e0.0, 2=\u003e0.0, 3=\u003e18.18, 4=\u003e10.0}\n```\nThis will sleep for 0.1 seconds. To be reliable, use a time like 0.05 seconds or so.\n\nIf you want to build a system monitor and don't want to wait, you have to do something like this:\n\n```\n#!/usr/bin/ruby\nrequire 'linux_stat'\n\nusages = []\nthread = Thread.new { }\ncounter = 0\n\nwhile true\n\tthread = Thread.new { usages = LinuxStat::CPU.usages(0.5).values } unless thread.alive?\n\n\t# clears the screen and prints the info\n\tputs \"\\e[2J\\e[H\\e[3J\"\\\n\t\"#{counter += 1}\\n\"\\\n\t\"\\e[1;33mTotal CPU Usage:\\e[0m #{usages[0]}%\\n\"\\\n\t\"#{usages[1..-1].to_a.map.with_index { |x, i| \"\\e[1;33mCore #{i}\\e[0m =\u003e #{x}%\\n\" }.join}\"\\\n\t\"Total Download: #{LinuxStat::PrettifyBytes.convert_decimal LinuxStat::Net.total_bytes_received}\\n\"\\\n\t\"Total Upload: #{LinuxStat::PrettifyBytes.convert_decimal LinuxStat::Net.total_bytes_transmitted}\"\nend\n```\n\nThis will not wait in every loop for 0.5 seconds, but it will not update the cpu usage in every loop either.\nSo what you will be seeing in the CPU usage in every 0.5 seconds interval.\n\nYou will also see the counter increases like crazy. Which means it's not getting waited for 0.5 seconds.\n\nBut the other methods doesn't have this delay, thus in this example,\nyou will be able see the \"Total Download\" and \"Total Upload\" in real time,\nwell as soon as the Linux kernel updates the data and ruby executes the loop.\n\nJust run the linuxstat.rb command to test what method takes what time measured in microseconds.\n\n## Note 2: Count CPU\n\nThere are confusingly 6 different methods to count the number of CPU. But they are here for a reason!\n\nWell this section actually demystifies the methods.\n\n1. The good old `LinuxStat::CPU.count()`:\n\nIt gets the configured CPU for the system. It doesn't count for hotplugged CPU.\nIf 3 out of 4 CPU are hotplugged out, it will still show 4. It calls `sysconf(_SC_NPROCESSORS_CONF)`\n\n2. The mysterious `LinuxStat::ProcessInfo.nproc(pid = $$)`:\n\n[ Also aliased to `LinuxStat::ProcessInfo.count_cpu()` ]\n\nIt returns the number of processors, like the other 3 methods.\nWithout any arguments, it's like running `require 'etc' ; puts Etc.nprocessors`\n\nSo there the caveat of checking what the number of processors are actually allocated to the pid.\n\nFor example:\n\n```\n$ ruby -r linux_stat -e \"puts LS::ProcessInfo.nproc\"\n4\n\n$ taskset -c 0 ruby -r linux_stat -e \"puts LS::ProcessInfo.nproc\"\n1\n\n$ taskset -c 0-1 ruby -r linux_stat -e \"puts LS::ProcessInfo.nproc\"\n2\n\n$ taskset -c 0-1,3 ruby -r linux_stat -e \"puts LS::ProcessInfo.nproc\"\n3\n\n$ taskset -c 0-1,3 ruby -r linux_stat -e \"puts LS::ProcessInfo.nproc \"\n3\n```\n\nOr with argument:\n\n```\nirb(main):001:0\u003e require 'linux_stat'\n=\u003e true\n\nirb(main):002:0\u003e LinuxStat::ProcessInfo.command_name 4775\n=\u003e \"electron\"\n\nirb(main):003:0\u003e LinuxStat::ProcessInfo.nproc 4775\n=\u003e 4\n```\n\n3. The `LinuxStat::CPU.online()`:\n\nThis returns the number of online CPU as an Array. It doesn't get affected by taskset or anything.\n\nFor example:\n\n```\nirb(main):001:0\u003e require 'linux_stat'\n=\u003e true\n\nirb(main):002:0\u003e LinuxStat::CPU.online\n=\u003e [0, 1, 3]\n```\n\nBy using `LinuxStat::CPU.online.count` you count the actual online CPU on your system.\n\nAny n number of CPU can get hotplugged in and out, and this will report that correctly.\n\nIt just gets the info from /proc/stat; but if it fails it will read /sys/devices/system/cpu/online\nand parse the output to get an array.\n\n4. The `LinuxStat::CPU.count_online`\nIt's a more robust method that counts the online CPU. It shouldn't fail in most if not all cases!\nBut if it fails for some really spooky reasons, it will return nil.\n\n5. The `LinuxStat::CPU.offline()`:\n\nThis returns the number of offline CPU as an Array. It doesn't get affected by taskset or anything.\n\nFor example:\n\n```\nirb(main):001:0\u003e require 'linux_stat'\n=\u003e true\n\nirb(main):002:0\u003e LinuxStat::CPU.offline\n=\u003e [2]\n```\n\nAny n number of CPU can get hotplugged in and out, and this will report that correctly.\n\nIt just gets the info from /sys/devices/system/cpu/offline, and parses the output.\n\n6. The `LinuxStat::Sysconf.processor_configured()`:\n\nSounds repetitive! Actually yes, this is written in C, and it is called by `LinuxStat::CPU.count`.\n\nThe difference is that `LinuxStat::CPU.count` caches the return value, and this method doesn't.\n\n7. The `LinuxStat::Sysconf.processor_online()`:\n\nThis may again sound repititive to LinuxStat::CPU.online, but it's actually not!\n\nIf you are using while loops, it might not report the correct number of CPU everytime.\n\nWorst, it can take a long time to update the total number of CPU.\n\nThe benefit is, it's quite fast!\n\nIt's mostly here just for the sake of completeness to sysconf.\n\n## Note 3: Filesystem\n\nFilesystem can take arguments. By default it's '/' or the root of the system...\n\nBut for the sake of example, to get the free disk space of /, you do:\n\n```\n$ irb\nirb(main):001:0\u003e require 'linux_stat'\n=\u003e true\n\nirb(main):002:0\u003e LinuxStat::Filesystem.free('/').fdiv(1024 ** 3).to_s \u003c\u003c \" GiB\"\n=\u003e \"35.666873931884766 GiB\"\n```\n\nTo see the free and total space of a thumbdrive:\n\n```\n$ irb\nirb(main):001:0\u003e require 'linux_stat'\n=\u003e true\n\nirb(main):002:0\u003e LinuxStat::Mounts.mount_point('/dev/sdb1')\n=\u003e \"/run/media/sourav/5c2b7af7-d4c3-4ab4-a035-06d18ffc8e6f\"\n\nirb(main):003:0\u003e thumbdrive = _\n=\u003e \"/run/media/sourav/5c2b7af7-d4c3-4ab4-a035-06d18ffc8e6f\"\n\nirb(main):004:0\u003e LinuxStat::Filesystem.free(thumbdrive).fdiv(1024 ** 3).to_s \u003c\u003c \" GiB\"\n=\u003e \"2.504791259765625 GiB\"\n\nirb(main):005:0\u003e LinuxStat::Filesystem.total(thumbdrive).fdiv(1024 ** 3).to_s \u003c\u003c \" GiB\"\n=\u003e \"29.305004119873047 GiB\"\n```\n\n## Note 4: ProcessInfo\n\nAll the methods LinuxStat::ProcessInfo can take an argument containing the Process ID of a process.\nBy default it's $$ or the PID of the current process, ruby, itself.\n\nExample:\nSay you want to see how much CPU Firefox is consuming, for that you have to do the following (firefox can create a lot of child process though):\n\n1. Get the PID of Firefox:\n```\nLinuxStat::Process.names.find { |x| x[1].include? 'firefox' }[0]\n=\u003e 770 # but this differs all the time\n```\n\n2. Get the CPU usage:\n```\n$ irb\nirb(main):001:0\u003e require 'linux_stat'\n=\u003e true\n\nirb(main):002:0\u003e pid = LinuxStat::Process.names.find { |x| x[1].include? 'firefox' }[0]\n=\u003e 770\n\nirb(main):003:0\u003e LinuxStat::ProcessInfo.cpu_usage(pid: pid)\n=\u003e 0.0\n\nirb(main):004:0\u003e LinuxStat::ProcessInfo.cpu_usage(pid: pid)\n=\u003e 15.0\n```\n\nTo get the memory usage of Firefox (for example):\n\n```\n$ irb\nirb(main):001:0\u003e require 'linux_stat'\n=\u003e true\n\nirb(main):002:0\u003e LinuxStat::ProcessInfo.mem_stat(LinuxStat::Process.names.find { |x| x[1].include? 'firefox'.freeze }[0])\n=\u003e {:memory=\u003e468472, :virtual_memory=\u003e4754080, :resident_memory=\u003e814388}\n```\n\nTo get ONLY the memory usage in MiB:\n\n```\n$ irb\nirb(main):001:0\u003e require 'linux_stat'\n=\u003e true\n\nirb(main):002:0\u003e LinuxStat::ProcessInfo.memory(LinuxStat::Process.names.find { |x| x[1].include? 'firefox'.freeze }[0]).fdiv(1024).round(2).to_s \u003c\u003c \" MiB\"\n=\u003e \"467.51 MiB\"\n```\n\n## Note 5: FS\n\nLinuxStat::FS module gives you the raw info in Hash collected from statvfs.\n\nIt's not documented above because it's not suggested to run this directly. But it shouldn't cause any issue. `LinuxStat::Filesystem.stat_raw(fs = '/')` does that automatically.\n\nIt always requires an argument, and it's very fast. It directly calls the C API without any intermediate Ruby code.\n\nFor example, to get the info about '/' or root:\n\n```\n$ irb\nirb(main):001:0\u003e require 'linux_stat'\n=\u003e true\n\nirb(main):002:0\u003e LinuxStat::FS.stat('/')\n=\u003e {:block_size=\u003e4096, :fragment_size=\u003e4096, :blocks=\u003e29292283, :block_free=\u003e9349843, :block_avail_unpriv=\u003e9349843, :inodes=\u003e58612160, :free_inodes=\u003e56708247, :filesystem_id=\u003e2050, :mount_flags=\u003e1024, :max_filename_length=\u003e255}\n\nirb(main):003:0\u003e t = Time.now ; puts LinuxStat::FS.stat('/') ; Time.now - t\n{:block_size=\u003e4096, :fragment_size=\u003e4096, :blocks=\u003e29292283, :block_free=\u003e9349843, :block_avail_unpriv=\u003e9349843, :inodes=\u003e58612160, :free_inodes=\u003e56708247, :filesystem_id=\u003e2050, :mount_flags=\u003e1024, :max_filename_length=\u003e255}\n=\u003e 5.0468e-05\n```\n\nTo learn more about them, just run ri and the method name. To see all available methods.\n\n## Note 6: User\nMost of the LinuxStat::User supports arguments.\n\nFor example, to get a user's home by the username:\n\n```\n$ irb\nirb(main):001:0\u003e require 'linux_stat'\n=\u003e true\n\nirb(main):002:0\u003e LinuxStat::User.home_by_username('root')\n=\u003e \"/root\"\n\nirb(main):003:0\u003e LinuxStat::User.home_by_username('ftp')\n=\u003e \"/srv/ftp\"\n\nirb(main):004:0\u003e LinuxStat::User.home_by_username('mail')\n=\u003e \"/var/spool/mail\"\n```\n\nOr to get the user's home by the GID/UID:\n\n```\n$ irb\nirb(main):001:0\u003e require 'linux_stat'\n=\u003e true\n\nirb(main):002:0\u003e LinuxStat::User.homes_by_uid(1001)\n=\u003e [\"/home/userx\", \"/home/userz\"]\n\nirb(main):003:0\u003e LinuxStat::User.homes_by_uid(1000)\n=\u003e [\"/home/sourav\"]\n\nirb(main):004:0\u003e LinuxStat::User.home_by_gid(1001)\n=\u003e \"/home/userx\"\n\nirb(main):005:0\u003e LinuxStat::User.home_by_gid(1000)\n=\u003e \"/home/sourav\"\n\nirb(main):006:0\u003e LinuxStat::User.home_by_gid(0)\n=\u003e \"/root\"\n```\n\nOr to get the UID/GID by username:\n\n```\n$ irb\nirb(main):001:0\u003e require 'linux_stat'\n=\u003e true\n\nirb(main):002:0\u003e LinuxStat::User.uid_by_username('root')\n=\u003e 0\n\nirb(main):003:0\u003e LinuxStat::User.uid_by_username('ftp')\n=\u003e 14\n\nirb(main):004:0\u003e LinuxStat::User.gid_by_username('ftp')\n=\u003e 11\n\nirb(main):005:0\u003e LinuxStat::User.gid_by_username('InvalidUser')\n=\u003e nil\n```\n\nOr to get the current user (in docker for example):\n\n```\n$ irb\nirb(main):001:0\u003e require 'linux_stat'\n=\u003e true\n\nirb(main):002:0\u003e LinuxStat::User.get_current_user\n=\u003e \"x\"\n\nirb(main):003:0\u003e LinuxStat::User.get_user\n=\u003e \"x\"\n\nirb(main):004:0\u003e LinuxStat::User.get_login\n=\u003e \"\"\n```\n\nRight, the get_login() can return an empty string. But LinuxStat::User.get_user also aliased as LinuxStat::User.get_current_user shouldn't return an empty string under most circumstances.\n\n## Note 7: Hwdata\nThe PCI and USB modules actually rely on hwdata found in /usr/share/hwdata/.\nThe LS::USB.devices_stat and LS::PCI.devices_stat returns the information in a Hash:\n\n```\n$ ruby -r linux_stat -e \"puts LS::USB.devices_stat.to_s[0..200]\"\n[{:path=\u003e\"/sys/bus/usb/devices/1-1.2/\", :id=\u003e\"04d9:1203\", :vendor_id=\u003e\"04d9\", :product_id=\u003e\"1203\", :bus_num=\u003e1, :dev_num=\u003e7, :hwdata=\u003e{:vendor=\u003e\"Holtek Semiconductor, Inc.\", :product=\u003e\"Keyboard\"}, :aut\n```\n\nBut if the files are not available, it won't return hwdata related information.\n\nSo it's suggested to install hwdata. But you might face issues with heroku and\nother online PaaS where you can't install it. So Version 1.1.1+ comes with a module function called `hwdata_file = file`.\n\n+ You can use any usb.ids or pci.ids files:\n\n```\nLS::PCI.hwdata_file = File.join(__dir__, 'hwdata', 'pci.ids')\nLS::USB.hwdata_file = File.join(__dir__, 'hwdata', 'usb.ids')\n```\n\nAssuming that you have `pci.ids` and `usb.ids` under ./hwdata directory.\n\nOn rails, you can put this (replace `__dir__` with `Rails.root`) inside environment.rb.\n\nBut do note that the file can be set only once. It's suggested to do that in the beginning of your app.\n\n+ There's one method to check if the hwdata file was already set:\n\n```\nirb(main):001:0' require 'linux_stat'\n=\u003e true\n\nirb(main):002:0\u003e LS::USB.hwdata_file_set?\n=\u003e false\n\nirb(main):003:0\u003e LS::USB.devices_stat ; ''\n=\u003e \"\"\n\nirb(main):004:0\u003e LS::USB.hwdata_file_set?\n=\u003e true\n```\n\nIt works on USB and PCI modules.\n\nOnce the file is set, calling `LS::PCI.hwdata_file = file` is futile.\n\n+ Initializing hwdata can take 0.1 to 0.2 seconds at the first, so there's a method to initialize_hwdata at first:\n\n```\nirb(main):001:0\u003e require 'linux_stat'\n=\u003e true\n\nirb(main):002:0\u003e LS::PCI.initialize_hwdata\n=\u003e true\n\nirb(main):003:0\u003e LS::PCI.initialize_hwdata\n=\u003e false\n```\n\nIt will return true if it worked, else it will return false. It's intended to be done once.\n\nIf you don't initialize and call methods that utilizes hwdata, they will call it and the first\ncall may take 0.1 to 0.2 seconds, the consecutive calls will then take under a millisecond.\n\n## Note 8: PrettifyBytes\nOften times we need to work with KB, MB GB, TB, or KiB, MiB, GiB, TiB, etc.\nAnd we need some work to convert bytes to those units.\nBecause LinuxStat provides a lot of data in bytes, and kilobytes, it's quite tedious to convert them all the time.\nTo avoid such duplication, it comes with a PrettifyBytes module.\n\nFor example, to convert bytes to decimal suffixes:\n\n```\n$irb\nirb(main):001:0\u003e require 'linux_stat'\n=\u003e true\n\nirb(main):002:0\u003e LinuxStat::PrettifyBytes.convert_decimal(1000)\n=\u003e \"1.00 kilobyte\"\n\nirb(main):003:0\u003e LinuxStat::PrettifyBytes.convert_decimal(10000)\n=\u003e \"10.00 kilobytes\"\n\nirb(main):004:0\u003e LinuxStat::PrettifyBytes.convert_decimal(100000)\n=\u003e \"100.00 kilobytes\"\n\nirb(main):005:0\u003e LinuxStat::PrettifyBytes.convert_decimal(10 ** 13)\n=\u003e \"10.00 terabytes\"\n```\n\nTo convert bytes to binary suffixes:\n\n```\nirb(main):006:0\u003e LinuxStat::PrettifyBytes.convert_binary(1000)\n=\u003e \"1000.00 bytes\"\n\nirb(main):007:0\u003e LinuxStat::PrettifyBytes.convert_binary(10000)\n=\u003e \"9.77 kibibytes\"\n\nirb(main):008:0\u003e LinuxStat::PrettifyBytes.convert_binary(100000)\n=\u003e \"97.66 kibibytes\"\n\nirb(main):009:0\u003e LinuxStat::PrettifyBytes.convert_binary(10 ** 13)\n=\u003e \"9.09 tebibytes\"\n```\n\nTo convert them to short Metric decimal suffixes:\n\n```\nirb(main):010:0\u003e LinuxStat::PrettifyBytes.convert_short_decimal(1000)\n=\u003e \"1.00 kB\"\n\nirb(main):011:0\u003e LinuxStat::PrettifyBytes.convert_short_decimal(10000)\n=\u003e \"10.00 kB\"\n\nirb(main):012:0\u003e LinuxStat::PrettifyBytes.convert_short_decimal(100000)\n=\u003e \"100.00 kB\"\n\nirb(main):013:0\u003e LinuxStat::PrettifyBytes.convert_short_decimal(10 ** 13)\n=\u003e \"10.00 TB\"\n```\n\nTo convert them to short IEC binary suffixes:\n\n```\nirb(main):014:0\u003e LinuxStat::PrettifyBytes.convert_short_binary(1000)\n=\u003e \"1000 B\"\n\nirb(main):015:0\u003e LinuxStat::PrettifyBytes.convert_short_binary(10000)\n=\u003e \"9.77 KiB\"\n\nirb(main):016:0\u003e LinuxStat::PrettifyBytes.convert_short_binary(100000)\n=\u003e \"97.66 KiB\"\n\nirb(main):017:0\u003e LinuxStat::PrettifyBytes.convert_short_binary(10 ** 13)\n=\u003e \"9.09 TiB\"\n```\n\nIt can support values upto hundreds of yottabytes and yobibytes, or yb and yib. You can also do stuff like:\n\n```\n$ irb\nirb(main):001:0\u003e require 'linux_stat'\n=\u003e true\n\nirb(main):002:0\u003e LinuxStat::PrettifyBytes.convert_short_decimal(LinuxStat::Mounts.device_stat('/dev/sdb1')[:total])\n=\u003e \"31.47 GB\"\n\nirb(main):003:0\u003e LinuxStat::PrettifyBytes.convert_short_binary(LinuxStat::Mounts.device_stat('/dev/sdb1')[:total])\n=\u003e \"29.31 GiB\"\n\nirb(main):004:0\u003e LinuxStat::PrettifyBytes.convert_short_binary(LinuxStat::Mounts.device_stat('/dev/sdb1')[:used])\n=\u003e \"26.80 GiB\"\n\nirb(main):005:0\u003e LinuxStat::PrettifyBytes.convert_short_binary(LinuxStat::Mounts.device_stat('/dev/sdb1')[:available])\n=\u003e \"2.51 GiB\"\n```\n\nRead the ri documentation for more info.\n\n---\n\n## Return Types\n+ In general, if a method returns either a Float or a Integer or a Time, it will return a Float or Integer or Time in all cases. But if the status isn't available, it will return nil.\n\n+ If the method returns a Hash / Array, it will return return Hash / Array in all cases. If the status isn't available, it will return an empty Hash / Array.\n\n+ If the method returns a String, it will return return String in all cases. If the status isn't available, it will return an empty *frozen* String.\n\n+ It doesn't have implementation of any Error that gets raised in runtime for the ease of use.\n\n+ If you need to check some stat that returns an integer or float, and you get nil, you know it's not available, so you can work accordingly. But if you need the integer or float value in 0 to whatever format, you can use the .to_i or .to_f method on the object, nil will get converted to number then.\n\nIf some error is *raised* it should be reported as a bug.\n\n---\n\n## Ruby on Rails\n\n1. Just add `gem linux_stat`:\n\n```\n$ bundle add linux_stat\n```\n\nYou can use LinuxStat directly in rails.\n\n![RailsApp](https://raw.githubusercontent.com/Souravgoswami/linux_stat/master/images/rails.gif)\n\n---\n\n## Android\n\nLinuxStat does support Android OS. But it's not rigorously tested on all device like android apps.\n\nBut in Termux you can just run LinuxStat without facing issues.\nNote that the CPU count can differ due to hotplugging feature. So if you see the CPU count changes, there's not really nothing to do about that.\n\n![termux](https://raw.githubusercontent.com/Souravgoswami/linux_stat/master/images/termux.webp)\n\nIssues regarding running LinuxStat on termux are also welcomed.\n\n---\n\n## Cloning this Repo\nUsers of this gem are requested to follow the above installation step to install this gem.\n\nThis repo is only for development purpose. It has C extensions that could do worst to your stable app.\nCloning, compiling code from this repo for a production app may seg fault and crash the whole app directly.\n\nGems on Rubygems are released after various tests.\n\nSo just install the gem, don't clone this repo just because the version is bumped here with new features, and the gem is not out on Rubygems.org.\n\n## Development\nAfter checking out the repo, compile and install this gem onto your local machine with `bundle exec rake install`\n\nYou can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo test all modules, run `rake install` and then `exe/linuxstat.rb`. Also check \"Testing\" below.\n\n---\n\n## Testing\nLike other gems, this doesn't have a test like RSpec.\n\nWe suggest using the exe/linuxstat.rb file on various Linux systems to test.\n\nFirst you need to execute `bundle exec rake install` to compile and install this gem.\n\nIf you need to test a specific module, say the CPU, just run it like this:\n\n```\n$ ruby exe/linuxstat.rb CPU\n```\n\nOr:\n```\n$ ruby exe/linuxstat.rb cpu\n```\n\nThat is, the argument passed is not case-sensitive.\nBut if the argument passed isn't available and outright wrong, it will run all the module methods. For example, you can't do:\n\n```\n$ ruby exe/linuxstat.rb upc\n```\nThis is not a valid module and can't be run.\n\n---\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/Souravgoswami/linux_stat.\n\n---\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n\n## Languages\n\n\u003cimg src=\"https://linuxstatloc.herokuapp.com/svg\" width=\"260px\"\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsouravgoswami%2Flinux_stat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsouravgoswami%2Flinux_stat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsouravgoswami%2Flinux_stat/lists"}