In Files

  • openssl/lib/openssl/buffering.rb

Class/Module Index [+]

Quicksearch

OpenSSL::Buffering

OpenSSL IO buffering mix-in module.

This module allows an OpenSSL::SSL::SSLSocket to behave like an IO.

Constants

BLOCK_SIZE

Default size to read from or write to the SSLSocket for buffer operations.

Attributes

sync[RW]

The “sync mode” of the SSLSocket.

See IO#sync for full details.

Public Class Methods

new(*args) click to toggle source
 
               # File openssl/lib/openssl/buffering.rb, line 38
def initialize(*args)
  @eof = false
  @rbuffer = ""
  @sync = @io.sync
end
            

Public Instance Methods

<<(s) click to toggle source

Writes s to the stream. s will be converted to a String using String#to_s.

 
               # File openssl/lib/openssl/buffering.rb, line 383
def << (s)
  do_write(s)
  self
end
            
close() click to toggle source

Closes the SSLSocket and flushes any unwritten data.

 
               # File openssl/lib/openssl/buffering.rb, line 446
def close
  flush rescue nil
  sysclose
end
            
each(eol=$/) click to toggle source

Executes the block for every line in the stream where lines are separated by eol.

See also gets

 
               # File openssl/lib/openssl/buffering.rb, line 221
def each(eol=$/)
  while line = self.gets(eol)
    yield line
  end
end
            
Also aliased as: each_line
each_byte() click to toggle source

Calls the given block once for each byte in the stream.

 
               # File openssl/lib/openssl/buffering.rb, line 262
def each_byte # :yields: byte
  while c = getc
    yield(c.ord)
  end
end
            
each_line(eol=$/) click to toggle source
Alias for: each
eof() click to toggle source
Alias for: eof?
eof?() click to toggle source

Returns true if the stream is at file which means there is no more data to be read.

 
               # File openssl/lib/openssl/buffering.rb, line 293
def eof?
  fill_rbuff if !@eof && @rbuffer.empty?
  @eof && @rbuffer.empty?
end
            
Also aliased as: eof
flush() click to toggle source

Flushes buffered data to the SSLSocket.

 
               # File openssl/lib/openssl/buffering.rb, line 434
def flush
  osync = @sync
  @sync = true
  do_write ""
  return self
ensure
  @sync = osync
end
            
getc() click to toggle source

Reads one character from the stream. Returns nil if called at end of file.

 
               # File openssl/lib/openssl/buffering.rb, line 255
def getc
  read(1)
end
            
gets(eol=$/, limit=nil) click to toggle source

Reads the next “line+ from the stream. Lines are separated by eol. If limit is provided the result will not be longer than the given number of bytes.

eol may be a String or Regexp.

Unlike IO#gets the line read will not be assigned to +$_+.

Unlike IO#gets the separator must be provided if a limit is provided.

 
               # File openssl/lib/openssl/buffering.rb, line 197
def gets(eol=$/, limit=nil)
  idx = @rbuffer.index(eol)
  until @eof
    break if idx
    fill_rbuff
    idx = @rbuffer.index(eol)
  end
  if eol.is_a?(Regexp)
    size = idx ? idx+$&.size : nil
  else
    size = idx ? idx+eol.size : nil
  end
  if limit and limit >= 0
    size = [size, limit].min
  end
  consume_rbuff(size)
end
            
printf(s, *args) click to toggle source

Formats and writes to the stream converting parameters under control of the format string.

See Kernel#sprintf for format string details.

 
               # File openssl/lib/openssl/buffering.rb, line 426
def printf(s, *args)
  do_write(s % args)
  nil
end
            
puts(*args) click to toggle source

Writes args to the stream along with a record separator.

See IO#puts for full details.

 
               # File openssl/lib/openssl/buffering.rb, line 393
def puts(*args)
  s = ""
  if args.empty?
    s << "\n"
  end
  args.each{|arg|
    s << arg.to_s
    if $/ && /\n\z/ !~ s
      s << "\n"
    end
  }
  do_write(s)
  nil
end
            
read(size=nil, buf=nil) click to toggle source

Reads size bytes from the stream. If buf is provided it must reference a string which will receive the data.

See IO#read for full details.

 
               # File openssl/lib/openssl/buffering.rb, line 84
def read(size=nil, buf=nil)
  if size == 0
    if buf
      buf.clear
      return buf
    else
      return ""
    end
  end
  until @eof
    break if size && size <= @rbuffer.size
    fill_rbuff
  end
  ret = consume_rbuff(size) || ""
  if buf
    buf.replace(ret)
    ret = buf
  end
  (size && ret.empty?) ? nil : ret
end
            
read_nonblock(maxlen, buf=nil) click to toggle source

Reads at most maxlen bytes in the non-blocking manner.

When no data can be read without blocking it raises OpenSSL::SSL::SSLError extended by IO::WaitReadable or IO::WaitWritable.

IO::WaitReadable means SSL needs to read internally so #read_nonblock should be called again when the underlying IO is readable.

IO::WaitWritable means SSL needs to write internally so #read_nonblock should be called again after the underlying IO is writable.

#read_nonblock needs two rescue clause as follows:

# emulates blocking read (readpartial).
begin
  result = ssl.read_nonblock(maxlen)
rescue IO::WaitReadable
  IO.select([io])
  retry
rescue IO::WaitWritable
  IO.select(nil, [io])
  retry
end

Note that one reason that #read_nonblock writes to the underlying IO is when the peer requests a new TLS/SSL handshake. See openssl the FAQ for more details. www.openssl.org/support/faq.html

 
               # File openssl/lib/openssl/buffering.rb, line 165
def read_nonblock(maxlen, buf=nil)
  if maxlen == 0
    if buf
      buf.clear
      return buf
    else
      return ""
    end
  end
  if @rbuffer.empty?
    return sysread_nonblock(maxlen, buf)
  end
  ret = consume_rbuff(maxlen)
  if buf
    buf.replace(ret)
    ret = buf
  end
  raise EOFError if ret.empty?
  ret
end
            
readchar() click to toggle source

Reads a one-character string from the stream. Raises an EOFError at end of file.

 
               # File openssl/lib/openssl/buffering.rb, line 272
def readchar
  raise EOFError if eof?
  getc
end
            
readline(eol=$/) click to toggle source

Reads a line from the stream which is separated by eol.

Raises EOFError if at end of file.

 
               # File openssl/lib/openssl/buffering.rb, line 246
def readline(eol=$/)
  raise EOFError if eof?
  gets(eol)
end
            
readlines(eol=$/) click to toggle source

Reads lines from the stream which are separated by eol.

See also gets

 
               # File openssl/lib/openssl/buffering.rb, line 233
def readlines(eol=$/)
  ary = []
  while line = self.gets(eol)
    ary << line
  end
  ary
end
            
readpartial(maxlen, buf=nil) click to toggle source

Reads at most maxlen bytes from the stream. If buf is provided it must reference a string which will receive the data.

See IO#readpartial for full details.

 
               # File openssl/lib/openssl/buffering.rb, line 111
def readpartial(maxlen, buf=nil)
  if maxlen == 0
    if buf
      buf.clear
      return buf
    else
      return ""
    end
  end
  if @rbuffer.empty?
    begin
      return sysread(maxlen, buf)
    rescue Errno::EAGAIN
      retry
    end
  end
  ret = consume_rbuff(maxlen)
  if buf
    buf.replace(ret)
    ret = buf
  end
  raise EOFError if ret.empty?
  ret
end
            
ungetc(c) click to toggle source

Pushes character c back onto the stream such that a subsequent buffered character read will return it.

Unlike IO#getc multiple bytes may be pushed back onto the stream.

Has no effect on unbuffered reads (such as sysread).

 
               # File openssl/lib/openssl/buffering.rb, line 285
def ungetc(c)
  @rbuffer[0,0] = c.chr
end
            
write(s) click to toggle source

Writes s to the stream. If the argument is not a string it will be converted using String#to_s. Returns the number of bytes written.

 
               # File openssl/lib/openssl/buffering.rb, line 336
def write(s)
  do_write(s)
  s.bytesize
end
            
write_nonblock(s) click to toggle source

Writes str in the non-blocking manner.

If there is buffered data, it is flushed first. This may block.

#write_nonblock returns number of bytes written to the SSL connection.

When no data can be written without blocking it raises OpenSSL::SSL::SSLError extended by IO::WaitReadable or IO::WaitWritable.

IO::WaitReadable means SSL needs to read internally so #write_nonblock should be called again after the underlying IO is readable.

IO::WaitWritable means SSL needs to write internally so #write_nonblock should be called again after underlying IO is writable.

So #write_nonblock needs two rescue clause as follows.

# emulates blocking write.
begin
  result = ssl.write_nonblock(str)
rescue IO::WaitReadable
  IO.select([io])
  retry
rescue IO::WaitWritable
  IO.select(nil, [io])
  retry
end

Note that one reason that #write_nonblock reads from the underlying IO is when the peer requests a new TLS/SSL handshake. See the openssl FAQ for more details. www.openssl.org/support/faq.html

 
               # File openssl/lib/openssl/buffering.rb, line 374
def write_nonblock(s)
  flush
  syswrite_nonblock(s)
end
            

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please visit Documenting-ruby.org.

blog comments powered by Disqus