From: Matthew Dillon <dillon@apollo.backplane.com>
Date: Fri, 2 Mar 2018 02:57:11 +0000 (-0800)
Subject: world - Document extpread() and extpwrite()
X-Git-Tag: v5.3.0~136
X-Git-Url: https://gitweb.dragonflybsd.org/dragonfly.git/commitdiff_plain/fd1eff19b158ee642d93283d799f645187d92f80

world - Document extpread() and extpwrite()

* Document these DragonFly-specific system calls.
---

diff --git a/include/unistd.h b/include/unistd.h
index 8b33d13249..915ff3e4df 100644
--- a/include/unistd.h
+++ b/include/unistd.h
@@ -79,6 +79,19 @@ typedef	__uint32_t	uid_t;		/* XXX __uid_t */
 #define	F_TEST		3	/* test a section for locks by other procs */
 #endif
 
+/*
+ * Extended API support (DragonFly specific)
+ */
+#if __BSD_VISIBLE
+
+#define _HAVE_EXTEXIT		1
+#define _HAVE_EXTPREAD		1
+#define _HAVE_EXTPREADV		1
+#define _HAVE_EXTPWRITE		1
+#define _HAVE_EXTPWRITEV	1
+
+#endif
+
 /*
  * POSIX options and option groups we unconditionally do or don't
  * implement.  This list includes those options which are exclusively
diff --git a/lib/libc/sys/read.2 b/lib/libc/sys/read.2
index 798c397a50..4b6d850aa4 100644
--- a/lib/libc/sys/read.2
+++ b/lib/libc/sys/read.2
@@ -36,7 +36,9 @@
 .Nm read ,
 .Nm readv ,
 .Nm pread ,
-.Nm preadv
+.Nm preadv ,
+.Nm extpread ,
+.Nm extpreadv
 .Nd read input
 .Sh LIBRARY
 .Lb libc
@@ -52,6 +54,10 @@
 .Fn pread "int d" "void *buf" "size_t nbytes" "off_t offset"
 .Ft ssize_t
 .Fn preadv "int d" "const struct iovec *iov" "int iovcnt" "off_t offset"
+.Ft ssize_t
+.Fn extpread "int d" "void *buf" "size_t nbytes" "int flags" "off_t offset"
+.Ft ssize_t
+.Fn extpreadv "int d" "const struct iovec *iov" "int iovcnt" "int flags" "off_t offset"
 .Sh DESCRIPTION
 .Fn Read
 attempts to read
@@ -68,9 +74,11 @@ buffers specified by the members of the
 .Fa iov
 array: iov[0], iov[1], ..., iov[iovcnt\|\-\|1].
 The
-.Fn pread
+.Fn pread ,
+.Fn preadv ,
+.Fn extpread ,
 and
-.Fn preadv
+.Fn extpreadv
 calls perform the same function, but read from the specified position in
 the file without modifying the file pointer.
 .Pp
@@ -99,6 +107,32 @@ and
 will always fill an area completely before proceeding
 to the next.
 .Pp
+The
+.Fn extpread
+and
+.Fn extpreadv
+functions are
+.Dx
+specific
+and extend the specification further by allowing a flags argument
+to also be passed in, controlling blocking/non-blocking and other features
+on a call-by-call basis, ignoring the related default for the descriptor.
+Allowed flags are:
+.Bl -tag -width Er
+.It O_FBLOCKING
+Force the system call to operate in a blocking fashion.
+.It O_FNONBLOCKING
+Force the system call to operate in a non-blocking fashion.
+.It O_FAPPEND
+Force append mode for the operation.
+.It O_FOFFSET
+Force offset mode for the operation.
+.It O_FSYNCWRITE
+(ignored for reads)
+.It O_FASYNCWRITE
+(ignored for reads)
+.El
+.Pp
 On objects capable of seeking, the
 .Fn read
 starts at a position
diff --git a/lib/libc/sys/write.2 b/lib/libc/sys/write.2
index 7ae6d6ee80..0ba9b05602 100644
--- a/lib/libc/sys/write.2
+++ b/lib/libc/sys/write.2
@@ -36,7 +36,9 @@
 .Nm write ,
 .Nm writev ,
 .Nm pwrite ,
-.Nm pwritev
+.Nm pwritev ,
+.Nm extpwrite ,
+.Nm extpwritev
 .Nd write output
 .Sh LIBRARY
 .Lb libc
@@ -52,6 +54,10 @@
 .Fn pwrite "int d" "const void *buf" "size_t nbytes" "off_t offset"
 .Ft ssize_t
 .Fn pwritev "int d" "const struct iovec *iov" "int iovcnt" "off_t offset"
+.Ft ssize_t
+.Fn extpwrite "int d" "const void *buf" "size_t nbytes" "int flags" "off_t offset"
+.Ft ssize_t
+.Fn extpwritev "int d" "const struct iovec *iov" "int iovcnt" "int flags" "off_t offset"
 .Sh DESCRIPTION
 .Fn Write
 attempts to write
@@ -100,6 +106,32 @@ and
 will always write a complete area before proceeding
 to the next.
 .Pp
+The
+.Fn extpwrite
+and
+.Fn extpwritev
+functions are
+.Dx
+specific and
+extend the specification further by allowing a flags argument
+to also be passed in, controlling blocking/non-blocking and other features
+on a call-by-call basis, ignoring the related default for the descriptor.
+Allowed flags are:
+.Bl -tag -width Er
+.It O_FBLOCKING
+Force the system call to operate in a blocking fashion.
+.It O_FNONBLOCKING
+Force the system call to operate in a non-blocking fashion.
+.It O_FAPPEND
+Force append mode for the operation.
+.It O_FOFFSET
+Force offset mode for the operation.
+.It O_FSYNCWRITE
+Force the system call to issue the write synchronously.
+.It O_FASYNCWRITE
+Force the system call to issue the write asynchronously.
+.El
+.Pp
 On objects capable of seeking, the
 .Fn write
 starts at a position