Class: File

Inherits:
Object
  • Object
show all
Extended by:
Windows::File::Functions
Includes:
Windows::File::Constants, Windows::File::Structs
Defined in:
lib/win32/file.rb

Constant Summary collapse

WIN32_FILE_VERSION =

The version of the win32-file library

'0.7.0'

Constants included from Windows::File::Constants

Windows::File::Constants::DRIVE_CDROM, Windows::File::Constants::DRIVE_RAMDISK, Windows::File::Constants::DRIVE_REMOVABLE, Windows::File::Constants::FILE_ATTRIBUTE_NORMAL, Windows::File::Constants::FILE_ATTRIBUTE_REPARSE_POINT, Windows::File::Constants::FILE_FLAG_BACKUP_SEMANTICS, Windows::File::Constants::FILE_FLAG_OPEN_REPARSE_POINT, Windows::File::Constants::FILE_SHARE_READ, Windows::File::Constants::FILE_TYPE_CHAR, Windows::File::Constants::FILE_TYPE_UNKNOWN, Windows::File::Constants::GENERIC_READ, Windows::File::Constants::INVALID_FILE_ATTRIBUTES, Windows::File::Constants::INVALID_HANDLE_VALUE, Windows::File::Constants::IO_REPARSE_TAG_SYMLINK, Windows::File::Constants::NO_ERROR, Windows::File::Constants::OPEN_EXISTING

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Windows::File::Functions

attach_pfunc

Class Method Details

.basename(file, suffix = nil) ⇒ Object

Returns the last component of the filename given in filename. If suffix is given and present at the end of filename, it is removed. Any extension can be removed by giving an extension of “.*”.

This was reimplemented because the current version does not handle UNC paths properly, i.e. it should not return anything less than the root. In most other respects it is identical to the current implementation.

Unlike MRI, this version will convert all forward slashes to backslashes automatically.

Examples:

File.basename("C:\\foo\\bar.txt")         -> "bar.txt"
File.basename("C:\\foo\\bar.txt", ".txt") -> "bar"
File.basename("\\\\foo\\bar")             -> "\\\\foo\\bar"

Raises:

  • (TypeError) 


50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/win32/file.rb', line 50

def self.basename(file, suffix = nil)
  raise TypeError unless file.is_a?(String)
  raise TypeError unless suffix.is_a?(String) if suffix

  return file if file.empty? # Return an empty path as-is.

  encoding = file.encoding
  wfile = file.wincode

  # Return a root path as-is.
  if PathIsRootW(wfile)
    return file.tr(File::SEPARATOR, File::ALT_SEPARATOR)
  end

  ptr = FFI::MemoryPointer.from_string(wfile)

  PathStripPathW(ptr) # Gives us the basename

  if suffix
    if suffix == '.*'
      PathRemoveExtensionW(ptr)
    else
      ext = PathFindExtensionW(ptr).read_string(suffix.length * 2).wstrip

      if ext == suffix
        PathRemoveExtensionW(ptr)
      end
    end
  end

  wfile = ptr.read_bytes(wfile.size * 2).split("\000\000").first.tr(0.chr, '')
  file = wfile.encode(encoding)[/^[^\0]*/]
  file.sub!(/\\+\z/, '') # Trim trailing slashes

  file
end

.blksize(file) ⇒ Object

Returns the filesystem’s block size.



351
352
353
 
# File 'lib/win32/file.rb', line 351

def self.blksize(file)
  File::Stat.new(file).blksize
end

.blockdev?(file) ⇒ Boolean

Returns whether or not the file is a block device. For MS Windows a block device is a removable drive, cdrom or ramdisk.

Returns:

  • (Boolean) 


358
359
360
361
 
# File 'lib/win32/file.rb', line 358

def self.blockdev?(file)
  return false unless File.exists?(file)
  File::Stat.new(file).blockdev?
end

.chardev?(file) ⇒ Boolean

Returns whether or not the file is a character device.

Returns:

  • (Boolean) 


365
366
367
368
 
# File 'lib/win32/file.rb', line 365

def self.chardev?(file)
  return false unless File.exists?(file)
  File::Stat.new(file).chardev?
end

.directory?(file) ⇒ Boolean

Returns whether or not the file is a directory.

Returns:

  • (Boolean) 


372
373
374
375
 
# File 'lib/win32/file.rb', line 372

def self.directory?(file)
  return false unless File.exists?(file)
  File::Stat.new(file).directory?
end

.dirname(file) ⇒ Object

Returns all components of the filename given in filename except the last one.

This was reimplemented because the current version does not handle UNC paths properly, i.e. it should not return anything less than the root. In all other respects it is identical to the current implementation.

Also, this method will convert all forward slashes to backslashes.

Examples:

File.dirname("C:\\foo\\bar\\baz.txt") -> "C:\\foo\\bar"
File.dirname("\\\\foo\\bar")          -> "\\\\foo\\bar"

Raises:

  • (TypeError) 


101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/win32/file.rb', line 101

def self.dirname(file)
  raise TypeError unless file.is_a?(String)

  # Short circuit for empty paths
  return '.' if file.empty?

  # Store original encoding, restore it later
  encoding = file.encoding

  # Convert to UTF-16LE
  wfile = file.wincode

  # Return a root path as-is.
  if PathIsRootW(wfile)
    return file.tr(File::SEPARATOR, File::ALT_SEPARATOR)
  end

  ptr = FFI::MemoryPointer.from_string(wfile)

  # Remove trailing slashes if present
  while result = PathRemoveBackslashW(ptr)
    break unless result.empty?
  end

  # Remove trailing file name if present
  unless PathRemoveFileSpecW(ptr)
    raise SystemCallError.new("PathRemoveFileSpec", FFI.errno)
  end

  wfile = ptr.read_bytes(wfile.size * 2).split("\000\000").first

  # Empty paths, short relative paths
  if wfile.nil? or wfile.empty?
    return '.'
  end

  # Return to original encoding
  file = wfile.tr(0.chr, '').encode(encoding)

  file
end

.executable?(file) ⇒ Boolean Also known as: executable_real?

Returns whether or not the file is executable.

Returns:

  • (Boolean) 


379
380
381
382
 
# File 'lib/win32/file.rb', line 379

def self.executable?(file)
  return false unless File.exists?(file)
  File::Stat.new(file).executable?
end

.file?(file) ⇒ Boolean

Returns whether or not the file is a regular file.

Returns:

  • (Boolean) 


386
387
388
389
 
# File 'lib/win32/file.rb', line 386

def self.file?(file)
  return false unless File.exists?(file)
  File::Stat.new(file).file?
end

.ftype(file) ⇒ Object

Identifies the type of file. The return string is one of ‘file’, ‘directory’, ‘characterSpecial’, ‘socket’ or ‘unknown’.



394
395
396
 
# File 'lib/win32/file.rb', line 394

def self.ftype(file)
  File::Stat.new(file).ftype
end

.grpowned?(file) ⇒ Boolean

Returns true if the process owner’s ID is the same as one of the file’s groups.

Returns:

  • (Boolean) 


400
401
402
403
 
# File 'lib/win32/file.rb', line 400

def self.grpowned?(file)
  return false unless File.exists?(file)
  File::Stat.new(file).grpowned?
end

.join(*args) ⇒ Object

Join path string components together into a single string.

This method was reimplemented so that it automatically converts forward slashes to backslashes. It is otherwise identical to the core File.join method.

Examples:

File.join("C:", "foo", "bar") # => C:\foo\bar
File.join("foo", "bar")       # => foo\bar



154
155
156
 
# File 'lib/win32/file.rb', line 154

def self.join(*args)
  return join_orig(*args).tr("/", "\\")
end

.join_orig ⇒ Object 



15
 
# File 'lib/win32/file.rb', line 15

alias_method :join_orig, :join

.long_path(file) ⇒ Object

Returns path in long format. For example, if ‘SOMEFI~1.TXT’ was the argument provided, and the short representation for ‘somefile.txt’, then this method would return ‘somefile.txt’.

Note that certain file system optimizations may prevent this method from working as expected. In that case, you will get back the file name in 8.3 format.



182
183
184
185
186
187
188
189
190
191
 
# File 'lib/win32/file.rb', line 182

def self.long_path(file)
  buffer = 0.chr * 1024
  wfile  = file.wincode

  if GetLongPathNameW(wfile, buffer, buffer.size/2) == 0
    raise SystemCallError.new('GetLongPathName', FFI.errno)
  end

  buffer.wstrip
end

.lstat ⇒ Object

Returns a File::Stat object as defined in the win32-file-stat library.



471
472
473
 
# File 'lib/win32/file.rb', line 471

def self.stat(file)
  File::Stat.new(file)
end

.owned?(file) ⇒ Boolean

Returns whether or not the current process owner is the owner of the file.

Returns:

  • (Boolean) 


407
408
409
410
 
# File 'lib/win32/file.rb', line 407

def self.owned?(file)
  return false unless File.exists?(file)
  File::Stat.new(file).owned?
end

.pipe?(file) ⇒ Boolean Also known as: socket?

Returns whether or not the file is a pipe.

Returns:

  • (Boolean) 


414
415
416
417
 
# File 'lib/win32/file.rb', line 414

def self.pipe?(file)
  return false unless File.exists?(file)
  File::Stat.new(file).pipe?
end

.readable?(file) ⇒ Boolean

Returns whether or not the file is readable by the process owner.

Returns:

  • (Boolean) 


421
422
423
424
 
# File 'lib/win32/file.rb', line 421

def self.readable?(file)
  return false unless File.exists?(file)
  File::Stat.new(file).readable?
end

.readable_real?(file) ⇒ Boolean

Synonym for File.readable?

Returns:

  • (Boolean) 


428
429
430
431
 
# File 'lib/win32/file.rb', line 428

def self.readable_real?(file)
  return false unless File.exists?(file)
  File::Stat.new(file).readable_real?
end

.readlink(file) ⇒ Object

Returns the path of the of the symbolic link referred to by file.



308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
 
# File 'lib/win32/file.rb', line 308

def self.readlink(file)
  if exists?(file) && !symlink?(file)
    raise SystemCallError.new(22) # EINVAL, match the spec
  end

  wfile = file.wincode
  path  = 0.chr * 512

  if File.directory?(file)
    flags = FILE_FLAG_BACKUP_SEMANTICS
  else
    flags = FILE_ATTRIBUTE_NORMAL
  end

  begin
    handle = CreateFileW(
      wfile,
      GENERIC_READ,
      FILE_SHARE_READ,
      nil,
      OPEN_EXISTING,
      flags,
      0
    )

    if handle == INVALID_HANDLE_VALUE
      raise SystemCallError.new('CreateFile', FFI.errno)
    end

    if GetFinalPathNameByHandleW(handle, path, path.size/2, 0) == 0
      raise SystemCallError.new('GetFinalPathNameByHandle', FFI.errno)
    end
  ensure
    CloseHandle(handle)
  end

  path.wstrip[4..-1] # Remove leading backslashes + question mark
end

.realdirpath(file, relative_to = nil) ⇒ Object

Converts path to a full file path, with all symlinks resolved and relative paths made absolute. If a second parameter if present, it is used as the base for resolving leading relative path segments.

Unlike File.realpath, an error is not raised if the final path created using a relative path argument doesn’t exist. – On Windows we only modify the realpath method if the file is a symlink.



271
272
273
274
275
276
277
278
279
280
281
 
# File 'lib/win32/file.rb', line 271

def self.realdirpath(file, relative_to = nil)
  if symlink?(file)
    if relative_to
      File.join(relative_to, File.basename(readlink(file)))
    else
      readlink(file)
    end
  else
    realdirpath_orig(file, relative_to)
  end
end

.realdirpath_orig ⇒ Object 



17
 
# File 'lib/win32/file.rb', line 17

alias_method :realdirpath_orig, :realdirpath

.realpath(file, relative_to = nil) ⇒ Object

Converts path to a full file path, with all symlinks resolved and relative paths made absolute. If a second parameter if present, it is used as the base for resolving leading relative path segments. – On Windows we only modify the realpath method if the file is a symlink.



289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
 
# File 'lib/win32/file.rb', line 289

def self.realpath(file, relative_to = nil)
  if symlink?(file)
    if relative_to
      result = File.join(relative_to, File.basename(readlink(file)))
      if File.exists?(result)
        result
      else
        raise SystemCallError.new(result, 2) # Errno::ENOENT
      end
    else
      readlink(file)
    end
  else
    realpath_orig(file, relative_to)
  end
end

.realpath_orig ⇒ Object 



16
 
# File 'lib/win32/file.rb', line 16

alias_method :realpath_orig, :realpath

.short_path(file) ⇒ Object

Returns path in 8.3 format. For example, ‘c:documentation.doc’ would be returned as ‘c:docume~1.doc’.



196
197
198
199
200
201
202
203
204
205
 
# File 'lib/win32/file.rb', line 196

def self.short_path(file)
  buffer = 0.chr * 1024
  wfile  = file.wincode

  if GetShortPathNameW(wfile, buffer, buffer.size/2) == 0
    raise SystemCallError.new('GetShortPathName', FFI.errno)
  end

  buffer.wstrip
end

.split(file) ⇒ Object

Splits the given string into a directory and a file component and returns them in a two element array. This was reimplemented because the current version does not handle UNC paths properly.



162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/win32/file.rb', line 162

def self.split(file)
  array = []

  if file.empty? || PathIsRootW(file.wincode)
    array.push(file, '')
  else
    array.push(File.dirname(file), File.basename(file))
  end

  array
end

.stat(file) ⇒ Object

Returns a File::Stat object as defined in the win32-file-stat library.



435
436
437
 
# File 'lib/win32/file.rb', line 435

def self.stat(file)
  File::Stat.new(file)
end

.symlink(target, link) ⇒ Object

Creates a symbolic link called new_name for the file or directory old_name.

This method requires Windows Vista or later to work. Otherwise, it returns nil as per MRI.

Raises:

  • (TypeError) 


213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
 
# File 'lib/win32/file.rb', line 213

def self.symlink(target, link)
  raise TypeError unless target.is_a?(String)
  raise TypeError unless link.is_a?(String)

  flags = File.directory?(target) ? 1 : 0

  wlink = link.wincode
  wtarget = target.wincode

  unless CreateSymbolicLinkW(wlink, wtarget, flags)
    raise SystemCallError.new('CreateSymbolicLink', FFI.errno)
  end

  0 # Comply with spec
end

.symlink?(file) ⇒ Boolean

Returns whether or not file is a symlink.

Returns:

  • (Boolean) 


231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
 
# File 'lib/win32/file.rb', line 231

def self.symlink?(file)
  return false unless File.exists?(file)
  bool  = false
  wfile = file.wincode

  attrib = GetFileAttributesW(wfile)

  if attrib == INVALID_FILE_ATTRIBUTES
    raise SystemCallError.new('GetFileAttributes', FFI.errno)
  end

  if attrib & FILE_ATTRIBUTE_REPARSE_POINT > 0
    begin
      find_data = WIN32_FIND_DATA.new
      handle = FindFirstFileW(wfile, find_data)

      if handle == INVALID_HANDLE_VALUE
        raise SystemCallError.new('FindFirstFile', FFI.errno)
      end

      if find_data[:dwReserved0] == IO_REPARSE_TAG_SYMLINK
        bool = true
      end
    ensure
      CloseHandle(handle)
    end
  end

  bool
end

.world_readable?(file) ⇒ Boolean

Returns whether or not the file is readable by others. Note that this merely returns true or false, not permission bits (or nil).

Returns:

  • (Boolean) 


442
443
444
445
 
# File 'lib/win32/file.rb', line 442

def self.world_readable?(file)
  return false unless File.exists?(file)
  File::Stat.new(file).world_readable?
end

.world_writable?(file) ⇒ Boolean

Returns whether or not the file is writable by others. Note that this merely returns true or false, not permission bits (or nil).

Returns:

  • (Boolean) 


450
451
452
453
 
# File 'lib/win32/file.rb', line 450

def self.world_writable?(file)
  return false unless File.exists?(file)
  File::Stat.new(file).world_writable?
end

.writable?(file) ⇒ Boolean

Returns whether or not the file is writable by the current process owner.

Returns:

  • (Boolean) 


457
458
459
460
 
# File 'lib/win32/file.rb', line 457

def self.writable?(file)
  return false unless File.exists?(file)
  File::Stat.new(file).writable?
end

.writable_real?(file) ⇒ Boolean

Synonym for File.writable?

Returns:

  • (Boolean) 


464
465
466
467
 
# File 'lib/win32/file.rb', line 464

def self.writable_real?(file)
  return false unless File.exists?(file)
  File::Stat.new(file).writable_real?
end

Instance Method Details

#stat ⇒ Object

Same as MRI, except it returns a stat object using the win32-file-stat gem.



480
481
482
 
# File 'lib/win32/file.rb', line 480

def stat
  File::Stat.new(self.path)
end