Class: Net::SFTP::Protocol::V01::Attributes

Class | Net::SFTP::Protocol::V01::Attributes
In: | lib/net/sftp/protocol/01/attributes.rb lib/net/sftp/protocol/01/attributes.rb
Parent: | Object

A class representing the attributes of a file or directory on the server. It may be used to specify new attributes, or to query existing attributes.

To specify new attributes, just pass a hash as the argument to the constructor. The following keys are supported:

- :size:: the size of the file
- :uid:: the user-id that owns the file (integer)
- :gid:: the group-id that owns the file (integer)
- :owner:: the name of the user that owns the file (string)
- :group:: the name of the group that owns the file (string)
- :permissions:: the permissions on the file (integer, e.g. 0755)
- :atime:: the access time of the file (integer, seconds since epoch)
- :mtime:: the modification time of the file (integer, seconds since epoch)
- :extended:: a hash of name/value pairs identifying extended info

Likewise, when the server sends an Attributes object, all of the above attributes are exposed as methods (though not all will be set with non-nil values from the server).

### Methods

directory? directory? file? file? from_buffer from_buffer gid gid group group new new owner owner symbolic_type symbolic_type symlink? symlink? to_s to_s type type uid uid

### Constants

F_SIZE | = | 0x00000001
F_UIDGID | = | 0x00000002
F_PERMISSIONS | = | 0x00000004
F_ACMODTIME | = | 0x00000008
F_EXTENDED | = | 0x80000000
T_REGULAR | = | 1
T_DIRECTORY | = | 2
T_SYMLINK | = | 3
T_SPECIAL | = | 4
T_UNKNOWN | = | 5
T_SOCKET | = | 6
T_CHAR_DEVICE | = | 7
T_BLOCK_DEVICE | = | 8
T_FIFO | = | 9
F_SIZE | = | 0x00000001
F_UIDGID | = | 0x00000002
F_PERMISSIONS | = | 0x00000004
F_ACMODTIME | = | 0x00000008
F_EXTENDED | = | 0x80000000
T_REGULAR | = | 1
T_DIRECTORY | = | 2
T_SYMLINK | = | 3
T_SPECIAL | = | 4
T_UNKNOWN | = | 5
T_SOCKET | = | 6
T_CHAR_DEVICE | = | 7
T_BLOCK_DEVICE | = | 8
T_FIFO | = | 9

### Attributes

atime | [RW] | The last access time of the file
atime | [RW] | The last access time of the file
attributes | [R] | The hash of name/value pairs that backs this Attributes instance
attributes | [R] | The hash of name/value pairs that backs this Attributes instance
extended | [RW] | The hash of name/value pairs identifying extended information about the file
extended | [RW] | The hash of name/value pairs identifying extended information about the file
gid | [W] | The group-id of the user that owns the file
gid | [W] | The group-id of the user that owns the file
mtime | [RW] | The modification time of the file
mtime | [RW] | The modification time of the file
permissions | [RW] | The permissions on the file
permissions | [RW] | The permissions on the file
size | [RW] | The size of the file.
size | [RW] | The size of the file.
uid | [W] | The user-id of the user that owns the file
uid | [W] | The user-id of the user that owns the file

### Public Class methods

from_buffer(buffer)

Parses the given buffer and returns an Attributes object compsed from the data extracted from it.

[Source]

        # File lib/net/sftp/protocol/01/attributes.rb, line 59
    59:       def from_buffer(buffer)
    60:         flags = buffer.read_long
    61:         data = {}
    62:
    63:         elements.each do |name, type, condition|
    64:           if flags & condition == condition
    65:             if type == :special
    66:               data[name] = send("parse_#{name}", buffer)
    67:             else
    68:               data[name] = buffer.send("read_#{type}")
    69:             end
    70:           end
    71:         end
    72:
    73:         new(data)
    74:       end

from_buffer(buffer)

Parses the given buffer and returns an Attributes object compsed from the data extracted from it.

[Source]

        # File lib/net/sftp/protocol/01/attributes.rb, line 59
    59:       def from_buffer(buffer)
    60:         flags = buffer.read_long
    61:         data = {}
    62:
    63:         elements.each do |name, type, condition|
    64:           if flags & condition == condition
    65:             if type == :special
    66:               data[name] = send("parse_#{name}", buffer)
    67:             else
    68:               data[name] = buffer.send("read_#{type}")
    69:             end
    70:           end
    71:         end
    72:
    73:         new(data)
    74:       end

new(attributes={})

Create a new Attributes instance with the given attributes. The following keys are supported:

- :size:: the size of the file
- :uid:: the user-id that owns the file (integer)
- :gid:: the group-id that owns the file (integer)
- :owner:: the name of the user that owns the file (string)
- :group:: the name of the group that owns the file (string)
- :permissions:: the permissions on the file (integer, e.g. 0755)
- :atime:: the access time of the file (integer, seconds since epoch)
- :mtime:: the modification time of the file (integer, seconds since epoch)
- :extended:: a hash of name/value pairs identifying extended info

[Source]

         # File lib/net/sftp/protocol/01/attributes.rb, line 154
    154:     def initialize(attributes={})
    155:       @attributes = attributes
    156:     end

new(attributes={})

Create a new Attributes instance with the given attributes. The following keys are supported:

- :size:: the size of the file
- :uid:: the user-id that owns the file (integer)
- :gid:: the group-id that owns the file (integer)
- :owner:: the name of the user that owns the file (string)
- :group:: the name of the group that owns the file (string)
- :permissions:: the permissions on the file (integer, e.g. 0755)
- :atime:: the access time of the file (integer, seconds since epoch)
- :mtime:: the modification time of the file (integer, seconds since epoch)
- :extended:: a hash of name/value pairs identifying extended info

[Source]

         # File lib/net/sftp/protocol/01/attributes.rb, line 154
    154:     def initialize(attributes={})
    155:       @attributes = attributes
    156:     end

### Public Instance methods

directory?()

Returns true if these attributes appear to describe a directory.

[Source]

         # File lib/net/sftp/protocol/01/attributes.rb, line 246
    246:     def directory?
    247:       case type
    248:       when T_DIRECTORY then true
    249:       when T_UNKNOWN   then nil
    250:       else false
    251:       end
    252:     end

directory?()

Returns true if these attributes appear to describe a directory.

[Source]

         # File lib/net/sftp/protocol/01/attributes.rb, line 246
    246:     def directory?
    247:       case type
    248:       when T_DIRECTORY then true
    249:       when T_UNKNOWN   then nil
    250:       else false
    251:       end
    252:     end

file?()

Returns true if these attributes appear to describe a regular file.

[Source]

         # File lib/net/sftp/protocol/01/attributes.rb, line 264
    264:     def file?
    265:       case type
    266:       when T_REGULAR then true
    267:       when T_UNKNOWN then nil
    268:       else false
    269:       end
    270:     end

file?()

Returns true if these attributes appear to describe a regular file.

[Source]

         # File lib/net/sftp/protocol/01/attributes.rb, line 264
    264:     def file?
    265:       case type
    266:       when T_REGULAR then true
    267:       when T_UNKNOWN then nil
    268:       else false
    269:       end
    270:     end

gid()

Returns the group-id of the group that owns the file, or `nil` if that information is not available. If a :group key exists, but not a :gid key, the Etc module will be used to reverse lookup the id from the name. This might fail on some systems (e.g., Windows).

[Source]

         # File lib/net/sftp/protocol/01/attributes.rb, line 174
    174:     def gid
    175:       if attributes[:group] && !attributes.key?(:gid)
    176:         require 'etc'
    177:         attributes[:gid] = Etc.getgrnam(attributes[:group]).gid
    178:       end
    179:       attributes[:gid]
    180:     end

gid()

Returns the group-id of the group that owns the file, or `nil` if that information is not available. If a :group key exists, but not a :gid key, the Etc module will be used to reverse lookup the id from the name. This might fail on some systems (e.g., Windows).

[Source]

         # File lib/net/sftp/protocol/01/attributes.rb, line 174
    174:     def gid
    175:       if attributes[:group] && !attributes.key?(:gid)
    176:         require 'etc'
    177:         attributes[:gid] = Etc.getgrnam(attributes[:group]).gid
    178:       end
    179:       attributes[:gid]
    180:     end

group()

Returns the group name of the group that owns the file, or `nil` if that information is not available. If the :gid is given, but not the :group, the Etc module will be used to lookup the name from the id. This might fail on some systems (e.g. Windows).

[Source]

         # File lib/net/sftp/protocol/01/attributes.rb, line 198
    198:     def group
    199:       if attributes[:gid] && !attributes[:group]
    200:         require 'etc'
    201:         attributes[:group] = Etc.getgrgid(attributes[:gid].to_i).name
    202:       end
    203:       attributes[:group]
    204:     end

group()

Returns the group name of the group that owns the file, or `nil` if that information is not available. If the :gid is given, but not the :group, the Etc module will be used to lookup the name from the id. This might fail on some systems (e.g. Windows).

[Source]

         # File lib/net/sftp/protocol/01/attributes.rb, line 198
    198:     def group
    199:       if attributes[:gid] && !attributes[:group]
    200:         require 'etc'
    201:         attributes[:group] = Etc.getgrgid(attributes[:gid].to_i).name
    202:       end
    203:       attributes[:group]
    204:     end

owner()

Returns the username of the user that owns the file, or `nil` if that information is not available. If the :uid is given, but not the :owner, the Etc module will be used to lookup the name from the id. This might fail on some systems (e.g. Windows).

[Source]

         # File lib/net/sftp/protocol/01/attributes.rb, line 186
    186:     def owner
    187:       if attributes[:uid] && !attributes[:owner]
    188:         require 'etc'
    189:         attributes[:owner] = Etc.getpwuid(attributes[:uid].to_i).name
    190:       end
    191:       attributes[:owner]
    192:     end

owner()

Returns the username of the user that owns the file, or `nil` if that information is not available. If the :uid is given, but not the :owner, the Etc module will be used to lookup the name from the id. This might fail on some systems (e.g. Windows).

[Source]

         # File lib/net/sftp/protocol/01/attributes.rb, line 186
    186:     def owner
    187:       if attributes[:uid] && !attributes[:owner]
    188:         require 'etc'
    189:         attributes[:owner] = Etc.getpwuid(attributes[:uid].to_i).name
    190:       end
    191:       attributes[:owner]
    192:     end

symbolic_type()

Returns the type as a symbol, rather than an integer, for easier use in Ruby programs.

[Source]

         # File lib/net/sftp/protocol/01/attributes.rb, line 230
    230:     def symbolic_type
    231:       case type
    232:       when T_SOCKET       then :socket
    233:       when T_SYMLINK      then :symlink
    234:       when T_REGULAR      then :regular
    235:       when T_BLOCK_DEVICE then :block_device
    236:       when T_DIRECTORY    then :directory
    237:       when T_CHAR_DEVICE  then :char_device
    238:       when T_FIFO         then :fifo
    239:       when T_SPECIAL      then :special
    240:       when T_UNKNOWN      then :unknown
    241:       else raise NotImplementedError, "unknown file type #{type} (bug?)"
    242:       end
    243:     end

symbolic_type()

Returns the type as a symbol, rather than an integer, for easier use in Ruby programs.

[Source]

         # File lib/net/sftp/protocol/01/attributes.rb, line 230
    230:     def symbolic_type
    231:       case type
    232:       when T_SOCKET       then :socket
    233:       when T_SYMLINK      then :symlink
    234:       when T_REGULAR      then :regular
    235:       when T_BLOCK_DEVICE then :block_device
    236:       when T_DIRECTORY    then :directory
    237:       when T_CHAR_DEVICE  then :char_device
    238:       when T_FIFO         then :fifo
    239:       when T_SPECIAL      then :special
    240:       when T_UNKNOWN      then :unknown
    241:       else raise NotImplementedError, "unknown file type #{type} (bug?)"
    242:       end
    243:     end

symlink?()

Returns true if these attributes appear to describe a symlink.

[Source]

         # File lib/net/sftp/protocol/01/attributes.rb, line 255
    255:     def symlink?
    256:       case type
    257:       when T_SYMLINK then true
    258:       when T_UNKNOWN then nil
    259:       else false
    260:       end
    261:     end

symlink?()

Returns true if these attributes appear to describe a symlink.

[Source]

         # File lib/net/sftp/protocol/01/attributes.rb, line 255
    255:     def symlink?
    256:       case type
    257:       when T_SYMLINK then true
    258:       when T_UNKNOWN then nil
    259:       else false
    260:       end
    261:     end

to_s()

Convert the object to a string suitable for passing in an SFTP packet. This is the raw representation of the attribute packet payload, and is not intended to be human readable.

[Source]

         # File lib/net/sftp/protocol/01/attributes.rb, line 275
    275:     def to_s
    276:       prepare_serialization!
    277:
    278:       flags = 0
    279:
    280:       self.class.elements.each do |name, type, condition|
    281:         flags |= condition if attributes[name]
    282:       end
    283:
    284:       buffer = Net::SSH::Buffer.from(:long, flags)
    285:       self.class.elements.each do |name, type, condition|
    286:         if flags & condition == condition
    287:           if type == :special
    288:             send("encode_#{name}", buffer)
    289:           else
    290:             buffer.send("write_#{type}", attributes[name])
    291:           end
    292:         end
    293:       end
    294:
    295:       buffer.to_s
    296:     end

to_s()

Convert the object to a string suitable for passing in an SFTP packet. This is the raw representation of the attribute packet payload, and is not intended to be human readable.

[Source]

         # File lib/net/sftp/protocol/01/attributes.rb, line 275
    275:     def to_s
    276:       prepare_serialization!
    277:
    278:       flags = 0
    279:
    280:       self.class.elements.each do |name, type, condition|
    281:         flags |= condition if attributes[name]
    282:       end
    283:
    284:       buffer = Net::SSH::Buffer.from(:long, flags)
    285:       self.class.elements.each do |name, type, condition|
    286:         if flags & condition == condition
    287:           if type == :special
    288:             send("encode_#{name}", buffer)
    289:           else
    290:             buffer.send("write_#{type}", attributes[name])
    291:           end
    292:         end
    293:       end
    294:
    295:       buffer.to_s
    296:     end

type()

Inspects the permissions bits to determine what type of entity this attributes object represents. If will return one of the T_ constants.

[Source]

         # File lib/net/sftp/protocol/01/attributes.rb, line 208
    208:     def type
    209:       if    permissions & 0140000 == 0140000 then
    210:         T_SOCKET
    211:       elsif permissions & 0120000 == 0120000 then
    212:         T_SYMLINK
    213:       elsif permissions & 0100000 == 0100000 then
    214:         T_REGULAR
    215:       elsif permissions &  060000 ==  060000 then
    216:         T_BLOCK_DEVICE
    217:       elsif permissions &  040000 ==  040000 then
    218:         T_DIRECTORY
    219:       elsif permissions &  020000 ==  020000 then
    220:         T_CHAR_DEVICE
    221:       elsif permissions &  010000 ==  010000 then
    222:         T_FIFO
    223:       else
    224:         T_UNKNOWN
    225:       end
    226:     end

type()

Inspects the permissions bits to determine what type of entity this attributes object represents. If will return one of the T_ constants.

[Source]

         # File lib/net/sftp/protocol/01/attributes.rb, line 208
    208:     def type
    209:       if    permissions & 0140000 == 0140000 then
    210:         T_SOCKET
    211:       elsif permissions & 0120000 == 0120000 then
    212:         T_SYMLINK
    213:       elsif permissions & 0100000 == 0100000 then
    214:         T_REGULAR
    215:       elsif permissions &  060000 ==  060000 then
    216:         T_BLOCK_DEVICE
    217:       elsif permissions &  040000 ==  040000 then
    218:         T_DIRECTORY
    219:       elsif permissions &  020000 ==  020000 then
    220:         T_CHAR_DEVICE
    221:       elsif permissions &  010000 ==  010000 then
    222:         T_FIFO
    223:       else
    224:         T_UNKNOWN
    225:       end
    226:     end

uid()

Returns the user-id of the user that owns the file, or `nil` if that information is not available. If an :owner key exists, but not a :uid key, the Etc module will be used to reverse lookup the id from the name. This might fail on some systems (e.g., Windows).

[Source]

         # File lib/net/sftp/protocol/01/attributes.rb, line 162
    162:     def uid
    163:       if attributes[:owner] && !attributes.key?(:uid)
    164:         require 'etc'
    165:         attributes[:uid] = Etc.getpwnam(attributes[:owner]).uid
    166:       end
    167:       attributes[:uid]
    168:     end

uid()

Returns the user-id of the user that owns the file, or `nil` if that information is not available. If an :owner key exists, but not a :uid key, the Etc module will be used to reverse lookup the id from the name. This might fail on some systems (e.g., Windows).

[Source]

         # File lib/net/sftp/protocol/01/attributes.rb, line 162
    162:     def uid
    163:       if attributes[:owner] && !attributes.key?(:uid)
    164:         require 'etc'
    165:         attributes[:uid] = Etc.getpwnam(attributes[:owner]).uid
    166:       end
    167:       attributes[:uid]
    168:     end

[Validate]