# vmsplice

## NAME



           vmsplice - splice user pages to/from a pipe
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#define _GNU_SOURCE** /* See feature_test_macros(7) */
           **#include <fcntl.h>**
    
           **ssize_t vmsplice(int** _fd_**, const struct iovec ***_iov_**,**
                            **size_t** _nr_segs_**, unsigned int** _flags_**);**
    


## DESCRIPTION



           If _fd_ is opened for writing, the **vmsplice**() system call maps
           _nr_segs_ ranges of user memory described by _iov_ into a pipe.  If _fd_
           is opened for reading, the **vmsplice**() system call fills _nr_segs_
           ranges of user memory described by _iov_ from a pipe.  The file
           descriptor _fd_ must refer to a pipe.
    
           The pointer _iov_ points to an array of _iovec_ structures as
           described in iovec(3type).
    
           The _flags_ argument is a bit mask that is composed by ORing
           together zero or more of the following values:
    
           **SPLICE_F_MOVE**
                  Unused for **vmsplice**(); see splice(2).
    
           **SPLICE_F_NONBLOCK**
                  Do not block on I/O; see splice(2) for further details.
    
           **SPLICE_F_MORE**
                  Currently has no effect for **vmsplice**(), but may be
                  implemented in the future; see splice(2).
    
           **SPLICE_F_GIFT**
                  The user pages are a gift to the kernel.  The application
                  may not modify this memory ever, otherwise the page cache
                  and on-disk data may differ.  Gifting pages to the kernel
                  means that a subsequent splice(2) **SPLICE_F_MOVE** can
                  successfully move the pages; if this flag is not specified,
                  then a subsequent splice(2) **SPLICE_F_MOVE** must copy the
                  pages.  Data must also be properly page aligned, both in
                  memory and length.
    


## RETURN VALUE



           Upon successful completion, **vmsplice**() returns the number of bytes
           transferred to the pipe.  On error, **vmsplice**() returns -1 and
           _errno_ is set to indicate the error.
    


## ERRORS



           **EAGAIN SPLICE_F_NONBLOCK** was specified in _flags_ , and the operation
                  would block.
    
           **EBADF** _fd_ either not valid, or doesn't refer to a pipe.
    
           **EINVAL** _nr_segs_ is greater than **IOV_MAX** ; or memory not aligned if
                  **SPLICE_F_GIFT** set.
    
           **ENOMEM** Out of memory.
    


## STANDARDS



           Linux.
    


## NOTES



           **vmsplice**() follows the other vectorized read/write type functions
           when it comes to limitations on the number of segments being
           passed in.  This limit is **IOV_MAX** as defined in _< limits.h>_.
           Currently, this limit is 1024.
    
           **vmsplice**() really supports true splicing only from user memory to
           a pipe.  In the opposite direction, it actually just copies the
           data to user space.  But this makes the interface nice and
           symmetric and enables people to build on **vmsplice**() with room for
           future improvement in performance.
    


* * *