Vectored I/O

This article is about the I/O method. For the vector addressing type, see gather/scatter (vector addressing).

In computing, vectored I/O, also known as scatter/gather I/O, is a method of input and output by which a single procedure call sequentially reads data from multiple buffers and writes it to a single data stream (gather), or reads data from a data stream and writes it to multiple buffers (scatter), as defined in a vector of buffers. Scatter/gather refers to the process of gathering data from, or scattering data into, the given set of buffers. Vectored I/O can operate synchronously or asynchronously. The main reasons for using vectored I/O are efficiency and convenience.

Vectored I/O has several potential uses:

• Atomicity: if the particular vectored I/O implementation supports atomicity, a process can write into or read from a set of buffers to or from a file without risk that another thread or process might perform I/O on the same file between the first process' reads or writes, thereby corrupting the file or compromising the integrity of the input
• Concatenating output: an application that wants to write non-sequentially placed data in memory can do so in one vectored I/O operation. For example, writing a fixed-size header and its associated payload data that are placed non-sequentially in memory can be done by a single vectored I/O operation without first concatenating the header and the payload to another buffer
• Efficiency: one vectored I/O read or write can replace many ordinary reads or writes, and thus save on the overhead involved in syscalls
• Splitting input: when reading data held in a format that defines a fixed-size header, one can use a vector of buffers in which the first buffer is the size of that header; and the second buffer will contain the data associated with the header

Standards bodies document the applicable functions readv ^[1] and writev ^[2] in POSIX 1003.1-2001 and the Single UNIX Specification version 2. The Windows API has analogous functions ReadFileScatter and WriteFileGather; however, unlike the POSIX functions, they require the alignment of each buffer on a memory page. ^[3] Winsock provides separate WSASend and WSARecv functions without this requirement.

While working directly with a vector of buffers can be significantly harder than working with a single buffer, using higher-level APIs ^[4] for working efficiently can mitigate the difficulties.

Examples

The following example in the C programming language prints "Hello, Wikipedia Community!" to the standard output. Each word is saved into a single buffer and with only one call to writev(), all buffers are printed to the standard output.

#include<stdio.h>#include<stdlib.h>#include<string.h>#include<unistd.h>#include<sys/uio.h>intmain(intargc,char*argv[]){constcharbuf1[]="Hello, ";constcharbuf2[]="Wikipedia ";constcharbuf3[]="Community!\n";structiovecbufs[]={{.iov_base=(void*)buf1,.iov_len=strlen(buf1)},{.iov_base=(void*)buf2,.iov_len=strlen(buf2)},{.iov_base=(void*)buf3,.iov_len=strlen(buf3)},};if(writev(STDOUT_FILENO,bufs,sizeof(bufs)/sizeof(bufs[0]))==-1){perror("writev()");exit(EXIT_FAILURE);}returnEXIT_SUCCESS;}

Rust

Rust provides the write_vectored method on the Write trait. ^[5]

usestd::io::IoSlice;usestd::io::prelude::*;usestd::fs::File;fnmain()-> std::io::Result<()>{letdata1=[1;8];letdata2=[15;8];letio_slice1=IoSlice::new(&data1);letio_slice2=IoSlice::new(&data2);letmutbuffer=File::create("foo.txt")?;// Writes some prefix of the byte string, not necessarily all of it.buffer.write_vectored(&[io_slice1,io_slice2])?;Ok(())}

See also

• Zero copy

References

1. readv Archived 2008-09-05 at the Wayback Machine in the Single Unix Specification
2. writev Archived 2007-12-17 at the Wayback Machine in the Single Unix Specification
3. ReadFileScatter in MSDN Library
4. Vstr Archived 2017-03-05 at the Wayback Machine the Vectored String API
5. "Write in std::io - Rust". doc.rust-lang.org. Retrieved 26 January 2025.