rbs 2.8.4 → 3.8.1

data/stdlib/etc/0/etc.rbs

@@ -1,15 +1,15 @@
 # <!-- rdoc-file=ext/etc/etc.c -->
 # The Etc module provides access to information typically stored in files in the
-# /etc directory on Unix systems.
+# `/etc` directory on Unix systems.
 #
 # The information accessible consists of the information found in the
-# /etc/passwd and /etc/group files, plus information about the system's
-# temporary directory (/tmp) and configuration directory (/etc).
+# `/etc/passwd` and `/etc/group` files, plus information about the system's
+# temporary directory (`/tmp`) and configuration directory (`/etc`).
 #
 # The Etc module provides a more reliable way to access information about the
 # logged in user than environment variables such as +$USER+.
 #
-# ## Example:
+# **Example:**
 #
 #     require 'etc'
 #
@@ -27,7 +27,7 @@
 module Etc
   # <!--
   #   rdoc-file=ext/etc/etc.c
-  #   - confstr(p1)
+  #   - confstr(name)        ->  String
   # -->
   # Returns system configuration variable using confstr().
   #
@@ -46,27 +46,27 @@ module Etc
 
   # <!--
   #   rdoc-file=ext/etc/etc.c
-  #   - endgrent()
+  #   - endgrent
   # -->
-  # Ends the process of scanning through the /etc/group file begun by ::getgrent,
-  # and closes the file.
+  # Ends the process of scanning through the `/etc/group` file begun by
+  # ::getgrent, and closes the file.
   #
   def self?.endgrent: () -> void
 
   # <!--
   #   rdoc-file=ext/etc/etc.c
-  #   - endpwent()
+  #   - endpwent
   # -->
-  # Ends the process of scanning through the /etc/passwd file begun with
+  # Ends the process of scanning through the `/etc/passwd` file begun with
   # ::getpwent, and closes the file.
   #
   def self?.endpwent: () -> void
 
   # <!--
   #   rdoc-file=ext/etc/etc.c
-  #   - getgrent()
+  #   - getgrent     ->  Etc::Group
   # -->
-  # Returns an entry from the /etc/group file.
+  # Returns an entry from the `/etc/group` file.
   #
   # The first time it is called it opens the file and returns the first entry;
   # each successive call returns the next entry, or `nil` if the end of the file
@@ -80,16 +80,16 @@ module Etc
 
   # <!--
   #   rdoc-file=ext/etc/etc.c
-  #   - getgrgid(group_id)  ->       Group
+  #   - getgrgid(group_id)  ->       Etc::Group
   # -->
   # Returns information about the group with specified integer `group_id`, as
-  # found in /etc/group.
+  # found in `/etc/group`.
   #
   # The information is returned as a Group struct.
   #
   # See the unix manpage for `getgrgid(3)` for more detail.
   #
-  # ### Example:
+  # **Example:**
   #
   #     Etc.getgrgid(100)
   #     #=> #<struct Etc::Group name="users", passwd="x", gid=100, mem=["meta", "root"]>
@@ -98,16 +98,16 @@ module Etc
 
   # <!--
   #   rdoc-file=ext/etc/etc.c
-  #   - getgrnam(name)       ->  Group
+  #   - getgrnam(name)       ->  Etc::Group
   # -->
   # Returns information about the group with specified `name`, as found in
-  # /etc/group.
+  # `/etc/group`.
   #
   # The information is returned as a Group struct.
   #
   # See the unix manpage for `getgrnam(3)` for more detail.
   #
-  # ### Example:
+  # **Example:**
   #
   #     Etc.getgrnam('users')
   #     #=> #<struct Etc::Group name="users", passwd="x", gid=100, mem=["meta", "root"]>
@@ -134,9 +134,9 @@ module Etc
 
   # <!--
   #   rdoc-file=ext/etc/etc.c
-  #   - getpwent()
+  #   - getpwent     ->  Etc::Passwd
   # -->
-  # Returns an entry from the /etc/passwd file.
+  # Returns an entry from the `/etc/passwd` file.
   #
   # The first time it is called it opens the file and returns the first entry;
   # each successive call returns the next entry, or `nil` if the end of the file
@@ -150,15 +150,16 @@ module Etc
 
   # <!--
   #   rdoc-file=ext/etc/etc.c
-  #   - getpwnam(name)       ->  Passwd
+  #   - getpwnam(name)       ->  Etc::Passwd
   # -->
-  # Returns the /etc/passwd information for the user with specified login `name`.
+  # Returns the `/etc/passwd` information for the user with specified login
+  # `name`.
   #
   # The information is returned as a Passwd struct.
   #
   # See the unix manpage for `getpwnam(3)` for more detail.
   #
-  # ### Example:
+  # **Example:**
   #
   #     Etc.getpwnam('root')
   #     #=> #<struct Etc::Passwd name="root", passwd="x", uid=0, gid=0, gecos="root",dir="/root", shell="/bin/bash">
@@ -167,9 +168,10 @@ module Etc
 
   # <!--
   #   rdoc-file=ext/etc/etc.c
-  #   - getpwuid(uid)        ->  Passwd
+  #   - getpwuid(uid)        ->  Etc::Passwd
   # -->
-  # Returns the /etc/passwd information for the user with the given integer `uid`.
+  # Returns the `/etc/passwd` information for the user with the given integer
+  # `uid`.
   #
   # The information is returned as a Passwd struct.
   #
@@ -177,7 +179,7 @@ module Etc
   #
   # See the unix manpage for `getpwuid(3)` for more detail.
   #
-  # ### Example:
+  # **Example:**
   #
   #     Etc.getpwuid(0)
   #     #=> #<struct Etc::Passwd name="root", passwd="x", uid=0, gid=0, gecos="root",dir="/root", shell="/bin/bash">
@@ -186,16 +188,17 @@ module Etc
 
   # <!--
   #   rdoc-file=ext/etc/etc.c
-  #   - group()
+  #   - group { |struct| block }
+  #   - group                                ->  Etc::Group
   # -->
   # Provides a convenient Ruby iterator which executes a block for each entry in
-  # the /etc/group file.
+  # the `/etc/group` file.
   #
   # The code block is passed an Group struct.
   #
   # See ::getgrent above for details.
   #
-  # Example:
+  # **Example:**
   #
   #     require 'etc'
   #
@@ -208,7 +211,7 @@ module Etc
 
   # <!--
   #   rdoc-file=ext/etc/etc.c
-  #   - nprocessors()
+  #   - nprocessors  ->  Integer
   # -->
   # Returns the number of online processors.
   #
@@ -220,8 +223,7 @@ module Etc
   # *   sysconf(_SC_NPROCESSORS_ONLN): GNU/Linux, NetBSD, FreeBSD, OpenBSD,
   #     DragonFly BSD, OpenIndiana, Mac OS X, AIX
   #
-  #
-  # Example:
+  # **Example:**
   #
   #     require 'etc'
   #     p Etc.nprocessors #=> 4
@@ -230,7 +232,7 @@ module Etc
   # process is bound to specific cpus. This is intended for getting better
   # parallel processing.
   #
-  # Example: (Linux)
+  # **Example:** (Linux)
   #
   #     linux$ taskset 0x3 ./ruby -retc -e "p Etc.nprocessors"  #=> 2
   #
@@ -238,17 +240,17 @@ module Etc
 
   # <!--
   #   rdoc-file=ext/etc/etc.c
-  #   - Etc.passwd { |struct| block }        ->  Passwd
-  #   - Etc.passwd                   ->  Passwd
+  #   - passwd { |struct| block }
+  #   - passwd                               ->  Etc::Passwd
   # -->
   # Provides a convenient Ruby iterator which executes a block for each entry in
-  # the /etc/passwd file.
+  # the `/etc/passwd` file.
   #
   # The code block is passed an Passwd struct.
   #
   # See ::getpwent above for details.
   #
-  # Example:
+  # **Example:**
   #
   #     require 'etc'
   #
@@ -261,25 +263,25 @@ module Etc
 
   # <!--
   #   rdoc-file=ext/etc/etc.c
-  #   - setgrent()
+  #   - setgrent
   # -->
-  # Resets the process of reading the /etc/group file, so that the next call to
+  # Resets the process of reading the `/etc/group` file, so that the next call to
   # ::getgrent will return the first entry again.
   #
   def self?.setgrent: () -> void
 
   # <!--
   #   rdoc-file=ext/etc/etc.c
-  #   - setpwent()
+  #   - setpwent
   # -->
-  # Resets the process of reading the /etc/passwd file, so that the next call to
+  # Resets the process of reading the `/etc/passwd` file, so that the next call to
   # ::getpwent will return the first entry again.
   #
   def self?.setpwent: () -> void
 
   # <!--
   #   rdoc-file=ext/etc/etc.c
-  #   - sysconf(p1)
+  #   - sysconf(name)        ->  Integer
   # -->
   # Returns system configuration variable using sysconf().
   #
@@ -295,20 +297,21 @@ module Etc
 
   # <!--
   #   rdoc-file=ext/etc/etc.c
-  #   - sysconfdir()
+  #   - sysconfdir   ->  String
   # -->
   # Returns system configuration directory.
   #
-  # This is typically "/etc", but is modified by the prefix used when Ruby was
-  # compiled. For example, if Ruby is built and installed in /usr/local, returns
-  # "/usr/local/etc" on other platforms than Windows. On Windows, this always
-  # returns the directory provided by the system.
+  # This is typically `"/etc"`, but is modified by the prefix used when Ruby was
+  # compiled. For example, if Ruby is built and installed in `/usr/local`, returns
+  # `"/usr/local/etc"` on other platforms than Windows.
+  #
+  # On Windows, this always returns the directory provided by the system.
   #
   def self?.sysconfdir: () -> ::String
 
   # <!--
   #   rdoc-file=ext/etc/etc.c
-  #   - systmpdir()
+  #   - systmpdir    ->  String
   # -->
   # Returns system temporary directory; typically "/tmp".
   #
@@ -316,14 +319,14 @@ module Etc
 
   # <!--
   #   rdoc-file=ext/etc/etc.c
-  #   - uname()
+  #   - uname        -> hash
   # -->
   # Returns the system information obtained by uname system call.
   #
   # The return value is a hash which has 5 keys at least:
   #     :sysname, :nodename, :release, :version, :machine
   #
-  # Example:
+  # **Example:**
   #
   #     require 'etc'
   #     require 'pp'
@@ -649,13 +652,59 @@ module Etc
 
   SC_XOPEN_VERSION: Integer
 
+  # <!-- rdoc-file=ext/etc/etc.c -->
+  # The version
+  #
   VERSION: String
 
+  # <!-- rdoc-file=ext/etc/etc.c -->
+  # Group is a placeholder Struct for user group database on Unix systems.
+  #
+  # ### The struct contains the following members
+  #
+  # name
+  # :   contains the name of the group as a String.
+  #
+  # passwd
+  # :   contains the encrypted password as a String. An `'x'` is returned if
+  #     password access to the group is not available; an empty string is returned
+  #     if no password is needed to obtain membership of the group. This is
+  #     system-dependent.
+  #
+  # gid
+  # :   contains the group's numeric ID as an integer.
+  #
+  # mem
+  # :   is an Array of Strings containing the short login names of the members of
+  #     the group.
+  #
   class Group < Struct[untyped]
     extend Enumerable[untyped]
 
     def self.[]: (*untyped) -> untyped
 
+    # <!--
+    #   rdoc-file=ext/etc/etc.c
+    #   - Etc::Group.each { |group| block }   ->       Etc::Group
+    #   - Etc::Group.each                          ->     Enumerator
+    # -->
+    # Iterates for each entry in the `/etc/group` file if a block is given.
+    #
+    # If no block is given, returns the Enumerator.
+    #
+    # The code block is passed a Group struct.
+    #
+    # **Example:**
+    #
+    #     require 'etc'
+    #
+    #     Etc::Group.each {|g|
+    #       puts g.name + ": " + g.mem.join(', ')
+    #     }
+    #
+    #     Etc::Group.collect {|g| g.name}
+    #     Etc::Group.select {|g| !g.mem.empty?}
+    #
     def self.each: () -> untyped
 
     def self.inspect: () -> untyped
@@ -666,8 +715,6 @@ module Etc
 
     def self.new: (*untyped) -> untyped
 
-    public
-
     def gid: () -> Integer
 
     def gid=: (Integer new_gid) -> void
@@ -685,11 +732,86 @@ module Etc
     def passwd=: (String new_passwd) -> void
   end
 
+  # <!-- rdoc-file=ext/etc/etc.c -->
+  # Passwd is a placeholder Struct for user database on Unix systems.
+  #
+  # ### The struct contains the following members
+  #
+  # name
+  # :   contains the short login name of the user as a String.
+  #
+  # passwd
+  # :   contains the encrypted password of the user as a String. an `'x'` is
+  #     returned if shadow passwords are in use. An `'*'` is returned if the user
+  #     cannot log in using a password.
+  #
+  # uid
+  # :   contains the integer user ID (uid) of the user.
+  #
+  # gid
+  # :   contains the integer group ID (gid) of the user's primary group.
+  #
+  # dir
+  # :   contains the path to the home directory of the user as a String.
+  #
+  # shell
+  # :   contains the path to the login shell of the user as a String.
+  #
+  #
+  # ### The following members below are system-dependent
+  #
+  # gecos
+  # :   contains a longer String description of the user, such as a full name.
+  #     Some Unix systems provide structured information in the gecos field, but
+  #     this is system-dependent.
+  #
+  # change
+  # :   password change time(integer).
+  #
+  # quota
+  # :   quota value(integer).
+  #
+  # age
+  # :   password age(integer).
+  #
+  # class
+  # :   user access class(string).
+  #
+  # comment
+  # :   comment(string).
+  #
+  # expire
+  # :   account expiration time(integer).
+  #
   class Passwd < Struct[untyped]
     extend Enumerable[untyped]
 
     def self.[]: (*untyped) -> untyped
 
+    # <!--
+    #   rdoc-file=ext/etc/etc.c
+    #   - Etc::Passwd.each { |struct| block }  ->  Etc::Passwd
+    #   - Etc::Passwd.each                     ->  Enumerator
+    # -->
+    # Iterates for each entry in the `/etc/passwd` file if a block is given.
+    #
+    # If no block is given, returns the Enumerator.
+    #
+    # The code block is passed an Passwd struct.
+    #
+    # See Etc.getpwent above for details.
+    #
+    # **Example:**
+    #
+    #     require 'etc'
+    #
+    #     Etc::Passwd.each {|u|
+    #       puts u.name + " = " + u.gecos
+    #     }
+    #
+    #     Etc::Passwd.collect {|u| u.gecos}
+    #     Etc::Passwd.collect {|u| u.gecos}
+    #
     def self.each: () -> untyped
 
     def self.inspect: () -> untyped
@@ -700,8 +822,6 @@ module Etc
 
     def self.new: (*untyped) -> untyped
 
-    public
-
     def change: () -> Integer
 
     def change=: (Integer new_change) -> void