jlog_io.h

/*
 * Copyright (c) 2005-2008, Message Systems, Inc.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are
 * met:
 *
 *    * Redistributions of source code must retain the above copyright
 *      notice, this list of conditions and the following disclaimer.
 *    * Redistributions in binary form must reproduce the above
 *      copyright notice, this list of conditions and the following
 *      disclaimer in the documentation and/or other materials provided
 *      with the distribution.
 *    * Neither the name Message Systems, Inc. nor the names
 *      of its contributors may be used to endorse or promote products
 *      derived from this software without specific prior written
 *      permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef _JLOG_IO_H_
#define _JLOG_IO_H_

#ifdef __cplusplus
extern "C" {
#endif

#include "jlog_config.h"
#if HAVE_SYS_UIO_H
#include <sys/uio.h>
#endif

typedef struct _jlog_file jlog_file;

/**
 * opens a jlog_file
 *
 * since a jlog_file is a shared handle potentially used by many threads,
 * the underlying open mode is always O_RDWR; only the O_CREAT and O_EXCL
 * flags are honored
 * @return pointer to jlog_file on success, NULL on failure
 * @internal
 */
jlog_file *jlog_file_open(const char *path, int flags, int mode, int multi_process);

/**
 * closes a jlog_file
 * @return 1 on success, 0 on failure
 * @internal
 */
int jlog_file_close(jlog_file *f);

/**
 * exclusively locks a jlog_file against other processes and threads
 * @return 1 on success, 0 on failure
 * @internal
 */
int jlog_file_lock(jlog_file *f);

/**
 * unlocks a jlog_file
 * @return 1 on success, 0 on failure
 * @internal
 */
int jlog_file_unlock(jlog_file *f);

/**
 * preads from a jlog_file, retries EINTR
 * @return 1 if the read was fully satisfied, 0 otherwise
 * @internal
 */
int jlog_file_pread(jlog_file *f, void *buf, size_t nbyte, off_t offset);

/**
 * pwrites to a jlog_file, retries EINTR
 * @return 1 if the write was fully satisfied, 0 otherwise
 * @internal
 */
int jlog_file_pwrite(jlog_file *f, const void *buf, size_t nbyte, off_t offset);

/**
 * pwritevs to a jlog_file, retries EINTR. takes the expected bytes written as an argument.
 * @return 1 if the write was fully satisfied, 0 otherwise
 * @internal
 */
int jlog_file_pwritev_verify_return_value(jlog_file *f, const struct iovec *vecs, int iov_count, off_t offset,
                                          size_t expected_length);

/**
 * pwritevs to a jlog_file, retries EINTR. calculates the expected bytes written internally.
 * @return 1 if the write was fully satisfied, 0 otherwise
 * @internal
 */
int jlog_file_pwritev(jlog_file *f, const struct iovec *vec, int iov_count, off_t offset);

/**
 * calls fdatasync (if avalable) or fsync on the underlying filehandle
 * @return 1 on success, 0 on failure
 * @internal
 */
int jlog_file_sync(jlog_file *f);

/**
 * maps the entirety of a jlog_file into memory for reading and writing
 * @param[in] f the jlog_file on which you are operating
 * @param[out] base is set to the base of the mapped region
 * @param[out] len is set to the length of the mapped region
 * @return 1 on success, 0 on failure
 * @internal
 */
int jlog_file_map_rdwr(jlog_file *f, void **base, size_t *len);

/**
 * maps the entirety of a jlog_file into memory for reading
 * @param[out] map is set to the base of the mapped region
 * @param[out] len is set to the length of the mapped region
 * @return 1 on success, 0 on failure
 * @internal
 */
int jlog_file_map_read(jlog_file *f, void **base, size_t *len);

/**
 * gives the size of a jlog_file
 * @return size of file on success, -1 on failure
 * @internal
 */
off_t jlog_file_size(jlog_file *f);

/**
 * truncates a jlog_file, retries EINTR
 * @return 1 on success, 0 on failure
 * @internal
 */
int jlog_file_truncate(jlog_file *f, off_t len);

#ifdef __cplusplus
}  /* Close scope of 'extern "C"' declaration which encloses file. */
#endif

#endif /* _JLOG_IO_H_ */
/* vim:se ts=2 sw=2 et: */