libgslutil  1.2.3
Functions
Simple I/O utilities

Functions

int set_non_blocking (int fd)
 Set non-blocking mode on a file descriptor. Returns 0 on success, logs failures to syslog.
 
int clear_non_blocking (int fd)
 Clear non-blocking mode on a file descriptor. Returns 0 on success, logs failures to syslog.
 
int gsl_set_cloexec (int fd)
 Set close-on-exec() mode on a file descriptor. More...
 
int gsl_clear_cloexec (int fd)
 Clear close-on-exec() mode on a file descriptor. More...
 
int gsl_set_nonblocking (int fd)
 Set non-blocking mode on a file descriptor. More...
 
int gsl_clear_nonblocking (int fd)
 Clear non-blocking mode on a file descriptor. More...
 
int membuf_drain_input (struct membuf_t *m, int fd))
 Read input from a file into a memory buffer. More...
 
int membuf_drain_output (struct membuf_t *m, int fd))
 Drain output from a memory buffer to a file. More...
 
ssize_t safe_read_fixed (int fd, char *buf, size_t amt))
 Read fixed amount of data into memory. More...
 
ssize_t safe_pread_fixed (int fd, char *buf, size_t amt, int64_t offset))
 Read fixed amount of data into memory from position in file. More...
 
ssize_t safe_write_fixed (int fd, const char *buf, size_t amt))
 Write fixed amount of data from memory. More...
 
ssize_t safe_pwrite_fixed (int fd, const char *buf, size_t amt, int64_t offset))
 Write fixed amount of data from memory to position in file. More...
 
int poll_flags (int fd)
 Get poll(2) flags for file descriptor. More...
 
const char * display_poll_flags (int flags)
 Display poll(2) flags in human-readable form. More...
 

Detailed Description

Routines for helping with generic posix I/O.

Function Documentation

◆ gsl_set_cloexec()

int gsl_set_cloexec ( int  fd)

Set close-on-exec() mode on a file descriptor.

Parameters
fdFile descriptor.
Return values
0on success.
-1on error (and see errno).

◆ gsl_clear_cloexec()

int gsl_clear_cloexec ( int  fd)

Clear close-on-exec() mode on a file descriptor.

Parameters
fdFile descriptor.
Return values
0on success.
-1on error (and see errno).

◆ gsl_set_nonblocking()

int gsl_set_nonblocking ( int  fd)

Set non-blocking mode on a file descriptor.

Parameters
fdFile descriptor.
Return values
0on success.
-1on error (and see errno).

◆ gsl_clear_nonblocking()

int gsl_clear_nonblocking ( int  fd)

Clear non-blocking mode on a file descriptor.

Parameters
fdFile descriptor.
Return values
0on success.
-1on error (and see errno).

◆ membuf_drain_input()

int membuf_drain_input ( struct membuf_t *  m,
int  fd 
)

Read input from a file into a memory buffer.

Parameters
mMemory buffer to read data into.
fdFile descriptor to read from.
Returns
Number of bytes available in buffer.
Return values
-1on EOF or error (and see errno).

This function will read input from a file descriptor fd into the memory buffer m. It will attempt to drain as much input as possible from fd (which should be non-blocking). The return value is the number of bytes available in the buffer after the read (which will include any data already in the buffer).

If there is no data waiting to be collected and we get EAGAIN immediately, then we simply return the number of bytes remaining in the buffer (which may be 0 if the buffer was empty). We do not return -1 in this case.

If there is no data to read, and an EOF condition occurs (socket closed etc.) then -1 is returned and errno is set to EPIPE. If an error occurs (but not EAGAIN) then -1 is returned and errno set as per read(). Errors (except EPIPE and EAGAIN) are logged to syslog.

◆ membuf_drain_output()

int membuf_drain_output ( struct membuf_t *  m,
int  fd 
)

Drain output from a memory buffer to a file.

Parameters
mMemory buffer to write data from.
fdFile descriptor to write data to.
Returns
Number of bytes remaining in the buffer.
Return values
-1on error (and see errno).

This function will write data from a memory buffer m to the file descriptor fd. It will attempt to drain as much data as possible to fd (which may be non-blocking). The return value is the number of bytes remaining in the buffer after the write (zero if all output is written).

If an error occurs (but not EAGAIN), then it is logged to syslog and -1 is returned.

◆ safe_read_fixed()

ssize_t safe_read_fixed ( int  fd,
char *  buf,
size_t  amt 
)

Read fixed amount of data into memory.

Parameters
fdFile descriptor to read from.
bufBuffer to read into.
amtAmount to read.
Returns
Number of bytes read (should be amt normally, only shorter if EOF is reached).
Return values
-1on error (and see errno).

Like read(), only we always read the amount that was requested. This won't work for non-blocking sockets, since we will return with EAGAIN and no way of knowing how much was read. Restarts if interrupted.

◆ safe_pread_fixed()

ssize_t safe_pread_fixed ( int  fd,
char *  buf,
size_t  amt,
int64_t  offset 
)

Read fixed amount of data into memory from position in file.

Parameters
fdFile descriptor to read from.
bufBuffer to read into.
amtAmount to read.
offsetOffset to seek to before reading.
Returns
Number of bytes read (should be amt normally, only shorter if EOF is reached).
Return values
-1on error (and see errno).

Like pread(), only we always read the amount that was requested. This won't work for non-blocking sockets, since we will return with EAGAIN and no way of knowing how much was read. Restarts if interrupted. Doesn't affect file position pointer.

◆ safe_write_fixed()

ssize_t safe_write_fixed ( int  fd,
const char *  buf,
size_t  amt 
)

Write fixed amount of data from memory.

Parameters
fdFile descriptor to write to.
bufBuffer to write from.
amtAmount to write.
Returns
Number of bytes written (i.e. amt).
Return values
-1on error (and see errno).

Like write(), only we always write the full amount that was requested. This won't work for non-blocking sockets, since we will return with EAGAIN and no way of knowing how much was written. Restarts if interrupted.

◆ safe_pwrite_fixed()

ssize_t safe_pwrite_fixed ( int  fd,
const char *  buf,
size_t  amt,
int64_t  offset 
)

Write fixed amount of data from memory to position in file.

Parameters
fdFile descriptor to write to.
bufBuffer to write from.
amtAmount to write.
offsetOffset to seek to before reading.
Returns
Number of bytes written (i.e. amt).
Return values
-1on error (and see errno).

Like pwrite(), only we always write the full amount that was requested. This won't work for non-blocking sockets, since we will return with EAGAIN and no way of knowing how much was written. Restarts if interrupted. Doesn't affect file position pointer.

◆ poll_flags()

int poll_flags ( int  fd)

Get poll(2) flags for file descriptor.

Parameters
fdFile descriptor to poll.
Returns
Poll flags for the file descriptor fd.
Return values
-1on error (and see errno).

This function calls poll(2) with an immediate timeout on the file descriptor fd, returning the flags that are set (or -1 on error). The result can be passed directly to display_poll_flags().

◆ display_poll_flags()

const char* display_poll_flags ( int  flags)

Display poll(2) flags in human-readable form.

Parameters
flagsFlags to display.
Returns
Pointer to static null-terminated string buffer holding flag names.

This function prints a human-readable representation of the poll flag bitfield flags into an internal buffer, returning a pointer to that buffer. If flags is -1, prints "Error: %m" into the buffer instead.