world - Document extpread() and extpwrite()
authorMatthew Dillon <dillon@apollo.backplane.com>
Fri, 2 Mar 2018 02:57:11 +0000 (18:57 -0800)
committerMatthew Dillon <dillon@apollo.backplane.com>
Fri, 2 Mar 2018 02:58:59 +0000 (18:58 -0800)
* Document these DragonFly-specific system calls.

include/unistd.h
lib/libc/sys/read.2
lib/libc/sys/write.2

index 8b33d13..915ff3e 100644 (file)
@@ -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
index 798c397..4b6d850 100644 (file)
@@ -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
 .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
index 7ae6d6e..0ba9b05 100644 (file)
@@ -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
 .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