Differential D27743 Diff 81558 lib/libc/sys/aio_write.2

Changeset View

Standalone View

lib/libc/sys/aio_write.2

	Show All 18 Lines
	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)			.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT			.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY			.\" 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			.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	.\" SUCH DAMAGE.			.\" SUCH DAMAGE.
	.\"			.\"
	.\" $FreeBSD$			.\" $FreeBSD$
	.\"			.\"
	.Dd August 19, 2016			.Dd January 2, 2021
	.Dt AIO_WRITE 2			.Dt AIO_WRITE 2
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm aio_write			.Nm aio_write ,
				.Nm aio_writev
	.Nd asynchronous write to a file (REALTIME)			.Nd asynchronous write to a file (REALTIME)
	.Sh LIBRARY			.Sh LIBRARY
	.Lb libc			.Lb libc
	.Sh SYNOPSIS			.Sh SYNOPSIS
	.In aio.h			.In aio.h
	.Ft int			.Ft int
	.Fn aio_write "struct aiocb *iocb"			.Fn aio_write "struct aiocb *iocb"
				.In sys/uio.h
				.Ft int
				.Fn aio_writev "struct aiocb *iocb"
	.Sh DESCRIPTION			.Sh DESCRIPTION
	The			The
	.Fn aio_write			.Fn aio_write
	system call allows the calling process to write			and
	.Fa iocb->aio_nbytes			.Fn aio_writev
	from the buffer pointed to by			system calls allow the calling process to write
	.Fa iocb->aio_buf
	to the descriptor			to the descriptor
	.Fa iocb->aio_fildes .			.Fa iocb->aio_fildes .
	The call returns immediately after the write request has been enqueued			.Fn aio_write
				will write
				.Fa iocb->aio_nbytes
				from the buffer pointed to by
				.Fa iocb->aio_buf ,
				whereas
				.Fn aio_writev
				gathers the data from the
				.Fa iocb->aio_iovcnt
				buffers specified by the members of the
				.Fa iocb->aio_iov
				array.
				Both syscalls return immediately after the write request has been enqueued
	to the descriptor; the write may or may not have completed at the time			to the descriptor; the write may or may not have completed at the time
	the call returns.			the call returns.
	If the request could not be enqueued, generally due			If the request could not be enqueued, generally due
	to invalid arguments, the call returns without having enqueued the			to invalid arguments, the call returns without having enqueued the
	request.			request.
	.Pp			.Pp
				For
				.Fn aio_writev
				the
				.Fa iovec
				structure is defined in
				.Xr writev 2 .
				.Pp
	If			If
	.Dv O_APPEND			.Dv O_APPEND
	is set for			is set for
	.Fa iocb->aio_fildes ,			.Fa iocb->aio_fildes ,
	.Fn aio_write			write operations append to the file in the same order as the calls were
	operations append to the file in the same order as the calls were
	made.			made.
	If			If
	.Dv O_APPEND			.Dv O_APPEND
	is not set for the file descriptor, the write operation will occur at			is not set for the file descriptor, the write operation will occur at
	the absolute position from the beginning of the file plus			the absolute position from the beginning of the file plus
	.Fa iocb->aio_offset .			.Fa iocb->aio_offset .
	.Pp			.Pp
	If			If
	Show All 29 Lines
	.Fa iocb->aio_buf			.Fa iocb->aio_buf
	member of that structure references must remain valid until the			member of that structure references must remain valid until the
	operation has completed.			operation has completed.
	.Pp			.Pp
	The asynchronous I/O control buffer			The asynchronous I/O control buffer
	.Fa iocb			.Fa iocb
	should be zeroed before the			should be zeroed before the
	.Fn aio_write			.Fn aio_write
				or
				.Fn aio_writev
	system call to avoid passing bogus context information to the kernel.			system call to avoid passing bogus context information to the kernel.
	.Pp			.Pp
	Modifications of the Asynchronous I/O Control Block structure or the			Modifications of the Asynchronous I/O Control Block structure or the
	buffer contents are not allowed while the request is queued.			buffer contents are not allowed while the request is queued.
	.Pp			.Pp
	If the file offset in			If the file offset in
	.Fa iocb->aio_offset			.Fa iocb->aio_offset
	is past the offset maximum for			is past the offset maximum for
	.Fa iocb->aio_fildes ,			.Fa iocb->aio_fildes ,
	no I/O will occur.			no I/O will occur.
	.Sh RETURN VALUES			.Sh RETURN VALUES
	.Rv -std aio_write			.Rv -std aio_write aio_writev
	.Sh ERRORS			.Sh ERRORS
	The			The
	.Fn aio_write			.Fn aio_write
	system call will fail if:			and
				.Fn aio_writev
				system calls will fail if:
	.Bl -tag -width Er			.Bl -tag -width Er
	.It Bq Er EAGAIN			.It Bq Er EAGAIN
	The request was not queued because of system resource limitations.			The request was not queued because of system resource limitations.
				.It Bq Er EFAULT
				Part of
				.Fa aio_iov
				points outside the process's allocated address space.
	.It Bq Er EINVAL			.It Bq Er EINVAL
	The asynchronous notification method in			The asynchronous notification method in
	.Fa iocb->aio_sigevent.sigev_notify			.Fa iocb->aio_sigevent.sigev_notify
	is invalid or not supported.			is invalid or not supported.
	.It Bq Er EOPNOTSUPP			.It Bq Er EOPNOTSUPP
	Asynchronous write operations on the file descriptor			Asynchronous write operations on the file descriptor
	.Fa iocb->aio_fildes			.Fa iocb->aio_fildes
	are unsafe and unsafe asynchronous I/O operations are disabled.			are unsafe and unsafe asynchronous I/O operations are disabled.
	.El			.El
	.Pp			.Pp
	The following conditions may be synchronously detected when the			The following conditions may be synchronously detected when the
	.Fn aio_write			.Fn aio_write
				or
				.Fn aio_writev
	system call is made, or asynchronously, at any time thereafter.			system call is made, or asynchronously, at any time thereafter.
	If they			If they
	are detected at call time,			are detected at call time,
	.Fn aio_write			.Fn aio_write
				or
				.Fn aio_writev
	returns -1 and sets			returns -1 and sets
	.Va errno			.Va errno
	appropriately; otherwise the			appropriately; otherwise the
	.Fn aio_return			.Fn aio_return
	system call must be called, and will return -1, and			system call must be called, and will return -1, and
	.Fn aio_error			.Fn aio_error
	must be called to determine the actual value that would have been			must be called to determine the actual value that would have been
	returned in			returned in
	▲ Show 20 Lines • Show All 49 Lines • ▼ Show 20 Lines
	.Xr aio 4			.Xr aio 4
	.Sh STANDARDS			.Sh STANDARDS
	The			The
	.Fn aio_write			.Fn aio_write
	system call			system call
	is expected to conform to the			is expected to conform to the
	.St -p1003.1			.St -p1003.1
	standard.			standard.
				.Pp
				The
				.Fn aio_writev
				system call is a FreeBSD extension, and should not be used in portable code.
	.Sh HISTORY			.Sh HISTORY
	The			The
	.Fn aio_write			.Fn aio_write
	system call first appeared in			system call first appeared in
	.Fx 3.0 .			.Fx 3.0 .
				The
				.Fn aio_writev
				system call first appeared in
				.Fx 13.0 .
	.Sh AUTHORS			.Sh AUTHORS
	This manual page was written by			This manual page was written by
	.An Wes Peters Aq Mt wes@softweyr.com .			.An Wes Peters Aq Mt wes@softweyr.com .
	.Sh BUGS			.Sh BUGS
	Invalid information in			Invalid information in
	.Fa iocb->_aiocb_private			.Fa iocb->_aiocb_private
	may confuse the kernel.			may confuse the kernel.