# saga::filesystem::file Class Reference

The SAGA file package file API. More...

`#include <file.hpp>`

Inheritance diagram for saga::filesystem::file:

[legend]

List of all members.

## Public Member Functions
| file (session const &s, saga::url url, int mode=Read)
| Creates the object.
| file (saga::url url, int mode=Read)
| Creates the object.
| file (saga::object const &o)
| Creates the object.
| file (void)
| Creates the object.
| ~file (void)
| Destroys the object.
file & | operator= (saga::object const &o)
| Brief description starts here.
saga::off_t | get_size (void)
| Returns the number of bytes in the file.
saga::ssize_t | read (saga::mutable_buffer buffer, saga::ssize_t length=0)
| Reads up to length bytes from the file into the buffer.
saga::ssize_t | write (saga::const_buffer buffer, saga::ssize_t length=0)
| Writes up to length bytes from buffer into the file at the current file position.
saga::off_t | seek (saga::off_t offset, seek_mode mode)
| Reposition the file pointer.
void | read_v (std::vector< saga::filesystem::iovec > buffer_vec)
| Gather/scatter read.
void | write_v (std::vector< saga::filesystem::const_iovec > buffer_vec)
| Gather/scatter write.
saga::ssize_t | size_p (std::string pattern)
| Determine the storage size required for a pattern I/O operation.
saga::ssize_t | read_p (std::string pattern, saga::mutable_buffer buffer)
| Pattern-based read.
saga::ssize_t | write_p (std::string pattern, saga::const_buffer buffer)
| Pattern-based write.
std::vector< std::string > | modes_e ()
| List the extended modes available in this implementation, and/or on server side.
saga::size_t | size_e (std::string ext_mode, std::string specification)
| determine the storage size required for an extended I/O operation
saga::ssize_t | read_e (std::string ext_mode, std::string specification, saga::mutable_buffer buffer)
| Extended read.
saga::ssize_t | write_e (std::string ext_mode, std::string specification, saga::const_buffer buffer)
| Extended write.
## Static Public Member Functions
static file | create (session const &s, saga::url url, int mode=Read)
| Factory function resembling file(session, url, int) constructor.
static file | create (saga::url url, int mode=Read)
| Factory function resembling file(url, int) constructor.
template<typename Tag>
static saga::task | create (saga::url url, int mode=Read)
| Factory function resembling entry(url, int) constructor.

## Detailed Description

The SAGA file package file API.

This class represents an open file descriptor for read/write operations on a physical file. Its concept is similar to the file descriptor returned by the open (2) call in POSIX.

Example:

## Constructor & Destructor Documentation

saga::filesystem::file::file | ( | session const & | s,
|  | saga::url | url,
|  | int | mode = `Read` |
| ) |  |  |

Creates the object.

saga::filesystem::file::file | ( | saga::url | url,
|  | int | mode = `Read` |
| ) |  |  | `[explicit]`

Creates the object.

saga::filesystem::file::file | ( | saga::object const & | o | ) | `[explicit]`

Creates the object.

References saga::BadParameter, saga::object::File, and saga::object::get_type().

saga::filesystem::file::file | ( | void |  | ) |

Creates the object.

saga::filesystem::file::~file | ( | void |  | ) |

Destroys the object.

## Member Function Documentation

static file saga::filesystem::file::create | ( | session const & | s,
|  | saga::url | url,
|  | int | mode = `Read` |
| ) |  |  | `[inline, static]`

Factory function resembling file(session, url, int) constructor.

Reimplemented from saga::name_space::entry.

static file saga::filesystem::file::create | ( | saga::url | url,
|  | int | mode = `Read` |
| ) |  |  | `[inline, static]`

Factory function resembling file(url, int) constructor.

Reimplemented from saga::name_space::entry.

template<typename Tag>

static saga::task saga::filesystem::file::create | ( | saga::url | url,
|  | int | mode = `Read` |
| ) |  |  | `[inline, static]`

Factory function resembling entry(url, int) constructor.

Reimplemented from saga::name_space::entry.

file & saga::filesystem::file::operator= | ( | saga::object const & | o | ) |

Brief description starts here.

Reimplemented from saga::name_space::entry.

References saga::name_space::entry::operator=().

saga::off_t saga::filesystem::file::get_size | ( | void |  | ) | `[inline]`

Returns the number of bytes in the file.

saga::ssize_t saga::filesystem::file::read | ( | saga::mutable_buffer | buffer,
|  | saga::ssize_t | length = `0` |
| ) |  |  | `[inline]`

Reads up to length bytes from the file into the buffer.

Parameters:

  | length | Number of bytes to be read
  | buffer | Buffer to read into

Returns:
  Number of bytes successfully read

saga::ssize_t saga::filesystem::file::write | ( | saga::const_buffer | buffer,
|  | saga::ssize_t | length = `0` |
| ) |  |  | `[inline]`

Writes up to length bytes from buffer into the file at the current file position.

Parameters:

  | length | Number of bytes to write
  | buffer | Data to write

Returns:
  Number of bytes successfully written

saga::off_t saga::filesystem::file::seek | ( | saga::off_t | offset,
|  | seek_mode | mode |
| ) |  |  | `[inline]`

Reposition the file pointer.

Parameters:

  | offset | Offset in bytes to move pointer
  | mode | Offset is relative to mode

Returns:
  position of pointer after seek

void saga::filesystem::file::read_v | ( | std::vector< saga::filesystem::iovec > | buffer_vec | ) | `[inline]`

Gather/scatter read.

Parameters:

  | buffer_vec | Array of buffer_vec structs defining start (offset) and length (length) of each individual read, buffer to read into, and integer to store result into.

void saga::filesystem::file::write_v | ( | std::vector< saga::filesystem::const_iovec > | buffer_vec | ) | `[inline]`

Gather/scatter write.

Parameters:

  | buffer_vec | Array of buffer_vec structs defining start (offset) and length (length) of each individual write, and buffers containing the data to write

saga::ssize_t saga::filesystem::file::size_p | ( | std::string | pattern | ) | `[inline]`

Determine the storage size required for a pattern I/O operation.

Parameters:

  | pattern | Pattern to determine size for

Returns:
  Size required for I/O operation with that pattern

saga::ssize_t saga::filesystem::file::read_p | ( | std::string | pattern,
|  | saga::mutable_buffer | buffer |
| ) |  |  | `[inline]`

Pattern-based read.

Parameters:

  | pattern | Pattern specification for read operation
  | buffer | Buffer to store read bytes into

Returns:
  Number of successfully read bytes

saga::ssize_t saga::filesystem::file::write_p | ( | std::string | pattern,
|  | saga::const_buffer | buffer |
| ) |  |  | `[inline]`

Pattern-based write.

Parameters:

  | pattern | Pattern specification for read operation
  | buffer | Buffer to store read bytes into

Returns:
  number of bytes successfully written

std::vector<std::string> saga::filesystem::file::modes_e | ( |  | ) | `[inline]`

List the extended modes available in this implementation, and/or on server side.

Parameters:

  | ret | Pattern to determine size for

Returns:
  Size required for I/O operation with that pattern

saga::size_t saga::filesystem::file::size_e | ( | std::string | ext_mode,
|  | std::string | specification |
| ) |  |  | `[inline]`

determine the storage size required for an extended I/O operation

saga::ssize_t saga::filesystem::file::read_e | ( | std::string | ext_mode,
|  | std::string | specification,
|  | saga::mutable_buffer | buffer |
| ) |  |  | `[inline]`

Extended read.

Parameters:

  | ext_mode | Extended mode to use
  | specification | Specification of read operation
  | buffer | Buffer to store read bytes into

Returns:
  Number of successfully read bytes

saga::ssize_t saga::filesystem::file::write_e | ( | std::string | ext_mode,
|  | std::string | specification,
|  | saga::const_buffer | buffer |
| ) |  |  | `[inline]`

Extended write.

Parameters:

  | ext_mode | Extended mode to use
  | specification | Specification of write operation
  | buffer | Buffer to store read bytes into

Returns:
  Number of successfully read bytes

The documentation for this class was generated from the following files:

- packages/file/file.hpp
- file.cpp