Module: Puppet::Etc Private

Defined in:
lib/puppet/etc.rb

Overview

This module is part of a private API. You should avoid using this module if possible, as it may be removed or be changed in the future.

On Ruby 2.1.0 and later, Etc returns strings in variable encoding depending on environment. The string returned will be labeled with the environment’s encoding (Encoding.default_external), with one exception: If the environment encoding is 7-bit ASCII, and any individual character bit representation is equal to or greater than 128 - x80 - 0b10000000 - signifying the smallest 8-bit big-endian value, the returned string will be in BINARY encoding instead of environment encoding.

Barring that exception, the returned string will be labeled as encoding Encoding.default_external, regardless of validity or byte-width. For example, ruby will label a string containing a four-byte characters such as “u2070E” as EUC_KR even though EUC_KR is a two-byte width encoding.

On Ruby 2.0.x and earlier, Etc will always return string values in BINARY, ignoring encoding altogether.

For Puppet we specifically want UTF-8 as our input from the Etc module - which is our input for many resource instance ‘is’ values. The associated ‘should’ value will basically always be coming from Puppet in UTF-8 - and written to disk as UTF-8. Etc is defined for Windows but the majority calls to it return nil and Puppet does not use it.

That being said, we have cause to retain the original, pre-override string values. ‘puppet resource user` (Puppet::Resource::User.indirection.search(’User’, {})) uses self.instances to query for user(s) and then iterates over the results of that query again to obtain state for each user. If we’ve overridden the original user name and not retained the original, we’ve lost the ability to query the system for it later. Hence the Puppet::Etc::Passwd and Puppet::Etc::Group structs.

We only use Etc for retrieving existing property values from the system. For setting property values, providers leverage system tools (i.e., ‘useradd`)

Class Method Summary collapse

Class Method Details

.endgrent ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

closes handle to /etc/group file



52
53
54
 
# File 'lib/puppet/etc.rb', line 52

def endgrent
  ::Etc.endgrent
end

.endpwent ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

closes handle to /etc/passwd file



69
70
71
 
# File 'lib/puppet/etc.rb', line 69

def endpwent
  ::Etc.endpwent
end

.getgrent ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Etc::getgrent returns an Etc::Group struct object On first call opens /etc/group and returns parse of first entry. Each subsquent call returns new struct the next entry or nil if EOF. Call ::endgrent to close file.



47
48
49
 
# File 'lib/puppet/etc.rb', line 47

def getgrent
  override_field_values_to_utf8(::Etc.getgrent)
end

.getgrgid(id) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Etc::getgrid searches /etc/group file for an entry corresponding to id. returns an Etc::Group struct corresponding to the entry or raises ArgumentError if none



96
97
98
 
# File 'lib/puppet/etc.rb', line 96

def getgrgid(id)
  override_field_values_to_utf8(::Etc.getgrgid(id))
end

.getgrnam(groupname) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Etc::getgrnam searches /etc/group file for an entry corresponding to groupname. returns an Etc::Group struct corresponding to the entry or raises ArgumentError if none



89
90
91
 
# File 'lib/puppet/etc.rb', line 89

def getgrnam(groupname)
  override_field_values_to_utf8(::Etc.getgrnam(groupname))
end

.getpwent ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Etc::getpwent returns an Etc::Passwd struct object On first call opens /etc/passwd and returns parse of first entry. Each subsquent call returns new struct for the next entry or nil if EOF. Call ::endgrent to close file.



64
65
66
 
# File 'lib/puppet/etc.rb', line 64

def getpwent
  override_field_values_to_utf8(::Etc.getpwent)
end

.getpwnam(username) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Etc::getpwnam searches /etc/passwd file for an entry corresponding to username. returns an Etc::Passwd struct corresponding to the entry or raises ArgumentError if none



82
83
84
 
# File 'lib/puppet/etc.rb', line 82

def getpwnam(username)
  override_field_values_to_utf8(::Etc.getpwnam(username))
end

.getpwuid(id) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Etc::getpwuid searches /etc/passwd file for an entry corresponding to id. returns an Etc::Passwd struct corresponding to the entry or raises ArgumentError if none



103
104
105
 
# File 'lib/puppet/etc.rb', line 103

def getpwuid(id)
  override_field_values_to_utf8(::Etc.getpwuid(id))
end

.group ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Etc::group returns a Ruby iterator that executes a block for each entry in the /etc/group file. The code-block is passed a Group struct. See getgrent above for more details.



110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/puppet/etc.rb', line 110

def group
  # The implementation here duplicates the logic in https://github.com/ruby/etc/blob/master/ext/etc/etc.c#L523-L537
  # Note that we do not call ::Etc.group directly, because we
  # want to use our wrappers for methods like getgrent, setgrent,
  # endgrent, etc.
  return getgrent unless block_given?

  setgrent
  begin
    while cur_group = getgrent # rubocop:disable Lint/AssignmentInCondition
      yield cur_group
    end
  ensure
    endgrent
  end
end

.setgrent ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

effectively equivalent to IO#rewind of /etc/group



57
58
59
 
# File 'lib/puppet/etc.rb', line 57

def setgrent
  ::Etc.setgrent
end

.setpwent ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

effectively equivalent to IO#rewind of /etc/passwd



74
75
76
 
# File 'lib/puppet/etc.rb', line 74

def setpwent
  ::Etc.setpwent
end