fd.h File Reference

exported symbols from fd.c More...

Functions
int	xrename (const char *oldpath, const char *newpath)
	Change the name or location of a file. More...
int	write_all (int fd, const char *buf, size_t len)
	Write to a file descriptor, fail on short writes. More...
__printf_2_3 int	write_va_buffer (int fd, const char *fmt,...)
	A fprintf-like function for raw file descriptors. More...
int	xpoll (struct pollfd *fds, nfds_t nfds, int timeout)
	Simple wrapper for poll(2). More...
__must_check int	mark_fd_nonblocking (int fd)
	Set a file descriptor to non-blocking mode. More...
__must_check int	mark_fd_blocking (int fd)
	Set a file descriptor to blocking mode. More...
int	para_mmap (size_t length, int prot, int flags, int fd, void *map)
	Paraslash's wrapper for mmap. More...
int	para_open (const char *path, int flags, mode_t mode)
	Wrapper for the open(2) system call. More...
int	para_mkdir (const char *path)
	Create a directory, don't fail if it already exists. More...
int	mmap_full_file (const char *filename, int open_mode, void **map, size_t *size, int *fd_ptr)
	Open a file and map it into memory. More...
int	para_munmap (void *start, size_t length)
	A wrapper for munmap(2). More...
int	read_ok (int fd)
	Check a file descriptor for readability. More...
int	write_ok (int fd)
	Check a file descriptor for writability. More...
void	valid_fd_012 (void)
	Ensure that file descriptors 0, 1, and 2 are valid. More...
int	readv_nonblock (int fd, struct iovec *iov, int iovcnt, size_t *num_bytes)
	Read from a non-blocking file descriptor into multiple buffers. More...
int	read_nonblock (int fd, void *buf, size_t sz, size_t *num_bytes)
	Read from a non-blocking file descriptor into a single buffer. More...
int	read_and_compare (int fd, const char *expectation)
	Read a buffer and compare its contents to a string, ignoring case. More...
int	xwrite (int fd, const char *buf, size_t len)
	Write a buffer to a file descriptor, re-writing on short writes. More...
int	xwritev (int fd, struct iovec *iov, int iovcnt)
	Write an array of buffers, handling non-fatal errors. More...
_static_inline_ int	write_buffer (int fd, const char *buf)
	Write a NULL-terminated buffer. More...

Detailed Description

exported symbols from fd.c

Function Documentation

xrename()

int xrename	(	const char *	oldpath,
		const char *	newpath
	)

Change the name or location of a file.

Parameters

oldpath	File to be moved.
newpath	Destination.

This is just a simple wrapper for the rename(2) system call which returns a paraslash error code and prints an error message on failure.

Returns

Standard.

See also

rename(2).

References ERRNO_TO_PARA_ERROR, and PARA_ERROR_LOG.

write_all()

int write_all	(	int	fd,
		const char *	buf,
		size_t	len
	)

Write to a file descriptor, fail on short writes.

Parameters

fd	The file descriptor.
buf	The buffer to be written.
len	The length of the buffer.

For blocking file descriptors this function behaves identical to xwrite(). For non-blocking file descriptors it returns -E_SHORT_WRITE (rather than a value less than len) if not all data could be written.

Returns

Number of bytes written on success, negative error code else.

References xwrite().

Referenced by pass_buffer_as_shm(), send_callback_request(), write_buffer(), and write_va_buffer().

write_va_buffer()

__printf_2_3 int write_va_buffer	(	int	fd,
		const char *	fmt,
			...
	)

A fprintf-like function for raw file descriptors.

This function creates a string buffer according to the given format and writes this buffer to a file descriptor.

Parameters

fd	The file descriptor.
fmt	A format string.

The difference to fprintf(3) is that the first argument is a file descriptor, not a FILE pointer. This function does not rely on stdio.

Returns

The return value of the underlying call to write_all().

See also

fprintf(3), xvasprintf().

References write_all(), and xvasprintf().

xpoll()

int xpoll	(	struct pollfd *	fds,
		nfds_t	nfds,
		int	timeout
	)

Simple wrapper for poll(2).

It calls poll(2) and starts over if the call was interrupted by a signal.

Parameters

fds	See poll(2).
nfds	See poll(2).
timeout	See poll(2).

Returns

The return value of the underlying poll() call on success, the negative paraslash error code on errors.

All arguments are passed verbatim to poll(2).

References ERRNO_TO_PARA_ERROR.

Referenced by read_ok(), schedule(), and write_ok().

mark_fd_nonblocking()

__must_check int mark_fd_nonblocking

(

int

fd

)

Set a file descriptor to non-blocking mode.

Parameters

fd	The file descriptor.

Returns

Standard.

References ERRNO_TO_PARA_ERROR.

Referenced by accept_sender_client(), and generic_com_on().

mark_fd_blocking()

__must_check int mark_fd_blocking

(

int

fd

)

Set a file descriptor to blocking mode.

Parameters

fd	The file descriptor.

Returns

Standard.

References ERRNO_TO_PARA_ERROR.

para_mmap()

int para_mmap	(	size_t	length,
		int	prot,
		int	flags,
		int	fd,
		void *	map
	)

Paraslash's wrapper for mmap.

Parameters

length	Number of bytes to mmap.
prot	Either PROT_NONE or the bitwise OR of one or more of PROT_EXEC PROT_READ PROT_WRITE.
flags	Exactly one of MAP_SHARED and MAP_PRIVATE.
fd	The file to mmap from.
map	Result pointer.

Returns

Standard.

See also

mmap(2).

References ERRNO_TO_PARA_ERROR.

Referenced by mmap_full_file().

para_open()

int para_open	(	const char *	path,
		int	flags,
		mode_t	mode
	)

Wrapper for the open(2) system call.

Parameters

path	The filename.
flags	The usual open(2) flags.
mode	Specifies the permissions to use.

The mode parameter must be specified when O_CREAT is in the flags, and is ignored otherwise.

Returns

The file descriptor on success, negative on errors.

See also

open(2).

References ERRNO_TO_PARA_ERROR.

Referenced by mmap_full_file().

para_mkdir()

int para_mkdir

(

const char *

path

)

Create a directory, don't fail if it already exists.

Parameters

path	Name of the directory to create.

This function passes the fixed mode value 0777 to mkdir(3) (which consults the file creation mask and restricts this value).

Returns

Zero if the path already existed as a directory or as a symbolic link which leads to a directory, one if the path did not exist and the directory has been created successfully, negative error code else.

References ERRNO_TO_PARA_ERROR.

mmap_full_file()

int mmap_full_file	(	const char *	path,
		int	open_mode,
		void **	map,
		size_t *	size,
		int *	fd_ptr
	)

Open a file and map it into memory.

Parameters

path	Name of the regular file to map.
open_mode	Either O_RDONLY or O_RDWR.
map	On success, the mapping is returned here.
size	size of the mapping.
fd_ptr	The file descriptor of the mapping.

If fd_ptr is NULL, the file descriptor resulting from the underlying open call is closed after mmap(). Otherwise the file is kept open and the file descriptor is returned in fd_ptr.

Returns

Standard.

See also

para_open(), mmap(2).

References ERRNO_TO_PARA_ERROR, para_mmap(), and para_open().

Referenced by decode_private_key(), and decode_public_key().

para_munmap()

int para_munmap	(	void *	start,
		size_t	length
	)

A wrapper for munmap(2).

Parameters

start	The start address of the memory mapping.
length	The size of the mapping.

If NULL is passed as the start address, the length value is ignored and the function does nothing.

Returns

Zero if NULL was passed, one if the memory area was successfully unmapped, a negative error code otherwise.

See also

munmap(2), mmap_full_file().

References ERRNO_TO_PARA_ERROR.

Referenced by decode_private_key().

read_ok()

int read_ok

(

int

fd

)

Check a file descriptor for readability.

Parameters

fd	The file descriptor.

Returns

positive if fd is ready for reading, zero if it isn't, negative if an error occurred.

See also

write_ok().

References xpoll().

write_ok()

int write_ok

(

int

fd

)

Check a file descriptor for writability.

Parameters

fd	The file descriptor.

Returns

positive if fd is ready for writing, zero if it isn't, negative if an error occurred.

See also

read_ok().

References xpoll().

valid_fd_012()

void valid_fd_012

(

void

)

Ensure that file descriptors 0, 1, and 2 are valid.

Common approach that opens /dev/null until it gets a file descriptor greater than two.

readv_nonblock()

int readv_nonblock	(	int	fd,
		struct iovec *	iov,
		int	iovcnt,
		size_t *	num_bytes
	)

Read from a non-blocking file descriptor into multiple buffers.

Parameters

fd	The file descriptor to read from.
iov	Scatter/gather array used in readv().
iovcnt	Number of elements in iov.
num_bytes	Result pointer. Contains the number of bytes read from fd.

This function tries to read up to sz bytes from fd, where sz is the sum of the lengths of all vectors in iov. Like xwrite(), EAGAIN and EINTR are not considered error conditions. However, EOF is.

Returns

Zero or a negative error code. If the underlying call to readv(2) returned zero (indicating an end of file condition) or failed for some reason other than EAGAIN or EINTR, a negative error code is returned.

In any case, num_bytes contains the number of bytes that have been successfully read from fd (zero if the first readv() call failed with EAGAIN). Note that even if the function returns negative, some data might have been read before the error occurred. In this case num_bytes is positive.

See also

xwrite(), read(2), readv(2).

References ERRNO_TO_PARA_ERROR.

Referenced by read_nonblock().

read_nonblock()

int read_nonblock	(	int	fd,
		void *	buf,
		size_t	sz,
		size_t *	num_bytes
	)

Read from a non-blocking file descriptor into a single buffer.

Parameters

fd	The file descriptor to read from.
buf	The buffer to read data to.
sz	The size of buf.
num_bytes

See also

readv_nonblock().

This is a simple wrapper for readv_nonblock() which uses an iovec with a single buffer.

Returns

The return value of the underlying call to readv_nonblock().

References readv_nonblock().

Referenced by para_next_signal(), and read_and_compare().

read_and_compare()

int read_and_compare	(	int	fd,
		const char *	expectation
	)

Read a buffer and compare its contents to a string, ignoring case.

Parameters

fd	The file descriptor to read from.
expectation	The expected string to compare to.

The given file descriptor is expected to be in non-blocking mode. The string comparison is performed using strncasecmp(3).

Returns

Zero if no data was available, positive if a buffer was read whose contents compare as equal to the expected string, negative otherwise. Possible errors: (a) not enough data was read, (b) the buffer contents compared as non-equal, (c) a read error occurred. In the first two cases, -E_READ_PATTERN is returned. In the read error case the (negative) return value of the underlying call to read_nonblock() is returned.

References alloc(), and read_nonblock().

xwrite()

int xwrite	(	int	fd,
		const char *	buf,
		size_t	len
	)

Write a buffer to a file descriptor, re-writing on short writes.

Parameters

fd	The file descriptor.
buf	The buffer to write.
len	The number of bytes to write.

This is a simple wrapper for xwritev().

Returns

The return value of the underlying call to xwritev().

References xwritev().

Referenced by send_queued_chunks(), and write_all().

xwritev()

int xwritev	(	int	fd,
		struct iovec *	iov,
		int	iovcnt
	)

Write an array of buffers, handling non-fatal errors.

Parameters

fd	The file descriptor to write to.
iov	Pointer to one or more buffers.
iovcnt	The number of buffers.

EAGAIN, EWOULDBLOCK and EINTR are not considered error conditions. If a write operation fails with EAGAIN or EWOULDBLOCK, the number of bytes that have been written so far is returned. In the EINTR case the operation is retried. Short writes are handled by issuing a subsequent write operation for the remaining part.

Returns

Negative on fatal errors, number of bytes written else.

For blocking file descriptors, this function returns either the sum of all buffer sizes or a negative error code which indicates the fatal error that caused a write call to fail.

For nonblocking file descriptors there is a third possibility: Any non-negative return value less than the sum of the buffer sizes indicates that a write operation returned EAGAIN/EWOULDBLOCK.

See also

writev(2), xwrite().

References ERRNO_TO_PARA_ERROR.

Referenced by send_sb(), and xwrite().

write_buffer()

_static_inline_ int write_buffer	(	int	fd,
		const char *	buf
	)

Write a NULL-terminated buffer.

Parameters

fd	The file descriptor.
buf	The null-terminated buffer to be send.

This is equivalent to write_all(fd, buf, strlen(buf)).

Returns

Standard.

References write_all().