1liburing 2-------- 3 4This is the io_uring library, liburing. liburing provides helpers to setup and 5teardown io_uring instances, and also a simplified interface for 6applications that don't need (or want) to deal with the full kernel 7side implementation. 8 9For more info on io_uring, please see: 10 11https://kernel.dk/io_uring.pdf 12 13Subscribe to io-uring@vger.kernel.org for io_uring related discussions 14and development for both kernel and userspace. The list is archived here: 15 16https://lore.kernel.org/io-uring/ 17 18 19kernel version dependency 20-------------------------- 21 22liburing itself is not tied to any specific kernel release, and hence it's 23possible to use the newest liburing release even on older kernels (and vice 24versa). Newer features may only be available on more recent kernels, 25obviously. 26 27 28ulimit settings 29--------------- 30 31io_uring accounts memory it needs under the rlimit memlocked option, which 32can be quite low on some setups (64K). The default is usually enough for 33most use cases, but bigger rings or things like registered buffers deplete 34it quickly. root isn't under this restriction, but regular users are. Going 35into detail on how to bump the limit on various systems is beyond the scope 36of this little blurb, but check /etc/security/limits.conf for user specific 37settings, or /etc/systemd/user.conf and /etc/systemd/system.conf for systemd 38setups. This affects 5.11 and earlier, new kernels are less dependent 39on RLIMIT_MEMLOCK as it is only used for registering buffers. 40 41 42Regressions tests 43----------------- 44 45The bulk of liburing is actually regression/unit tests for both liburing and 46the kernel io_uring support. Please note that this suite isn't expected to 47pass on older kernels, and may even crash or hang older kernels! 48 49 50Building liburing 51----------------- 52 53 # 54 # Prepare build config (optional). 55 # 56 # --cc specifies the C compiler. 57 # --cxx specifies the C++ compiler. 58 # 59 ./configure --cc=gcc --cxx=g++; 60 61 # 62 # Build liburing. 63 # 64 make -j$(nproc); 65 66 # 67 # Install liburing (headers, shared/static libs, and manpage). 68 # 69 sudo make install; 70 71See './configure --help' for more information about build config options. 72 73 74FFI support 75----------- 76 77By default, the build results in 4 lib files: 78 79 2 shared libs: 80 81 liburing.so 82 liburing-ffi.so 83 84 2 static libs: 85 86 liburing.a 87 liburing-ffi.a 88 89Languages and applications that can't use 'static inline' functions in 90liburing.h should use the FFI variants. 91 92liburing's main public interface lives in liburing.h as 'static inline' 93functions. Users wishing to consume liburing purely as a binary dependency 94should link against liburing-ffi. It contains definitions for every 'static 95inline' function. 96 97 98License 99------- 100 101All software contained within this repo is dual licensed LGPL and MIT, see 102COPYING and LICENSE, except for a header coming from the kernel which is 103dual licensed GPL with a Linux-syscall-note exception and MIT, see 104COPYING.GPL and <https://spdx.org/licenses/Linux-syscall-note.html>. 105 106Jens Axboe 2022-05-19 107