Libc-1439.100.3.tar.gz

[apple/libc.git] / libdarwin / h / stdio.h

diff --git a/libdarwin/h/stdio.h b/libdarwin/h/stdio.h
index 3042ce2e42ba0b78584de2ff043b7e14ca57a62c..dd7f2711336e7cef82e3ccbc47d9406ab38418ca 100644 (file)
--- a/libdarwin/h/stdio.h
+++ b/libdarwin/h/stdio.h
@@ -31,9 +31,206 @@
 #include <os/base.h>
 #include <os/api.h>
 #include <sys/cdefs.h>
 #include <os/base.h>
 #include <os/api.h>
 #include <sys/cdefs.h>

+#include <stdint.h>
+#include <stdbool.h>
+#include <stdio.h>
+#include <unistd.h>
+#include <sys/types.h>
+
+#if __has_include(<sys/guarded.h>)
+#include <sys/guarded.h>
+#else
+typedef uint64_t guardid_t;
+#endif
+
+#if DARWIN_TAPI
+#include "tapi.h"
+#endif

 
 __BEGIN_DECLS;
 
 
 __BEGIN_DECLS;
 

+/*!
+ * @typedef os_fd_t
+ * A type alias for a file descriptor.
+ */
+typedef int os_fd_t;
+
+/*!
+ * @function os_fd_valid
+ * Returns whether the given integer is a valid file descriptor number.
+ *
+ * @param fd
+ * The integer to check.
+ *
+ * @result
+ * A Boolean indicating whether the integer is a valid file descriptor number,
+ * that is, greater than or equal to zero.
+ */
+DARWIN_API_AVAILABLE_20180727
+OS_ALWAYS_INLINE OS_WARN_RESULT
+static inline bool
+os_fd_valid(os_fd_t fd)
+{
+       return (fd >= STDIN_FILENO);
+}
+
+/*!
+ * @function os_guardid_from_ptr
+ * Converts the given pointer to a guardid_t.
+ *
+ * @param p
+ * The pointer to convert.
+ *
+ * @result
+ * The pointer as a guardid_t.
+ */
+DARWIN_API_AVAILABLE_20190830
+OS_ALWAYS_INLINE OS_WARN_RESULT
+static inline guardid_t
+os_guardid_from_ptr(const void *p)
+{
+       return (guardid_t)(uintptr_t)p;
+}
+
+/*!
+ * @function fcheck_np
+ * Checks the status of an fread(3) or fwrite(3) operation to a FILE.
+ *
+ * @param f
+ * The file on which the operation was performed.
+ *
+ * @param n
+ * The return value of the operation.
+ *
+ * @param expected
+ * The expected return value of the operation.
+ *
+ * @result
+ * One of the following integers:
+ *
+ *     0     The operation succeeded
+ *     EOF   The operation encountered the end of the FILE stream before it
+ *           could complete
+ *     1     There was an error
+ */
+DARWIN_API_AVAILABLE_20180727
+OS_EXPORT OS_WARN_RESULT OS_NONNULL1
+int
+fcheck_np(FILE *f, size_t n, size_t expected);
+
+/*!
+ * @function dup_np
+ * Variant of dup(2) that guarantees the dup(2) operation will either succeed or
+ * not return.
+ *
+ * @param fd
+ * The descriptor to dup(2).
+ *
+ * @result
+ * A new file descriptor number that is functionally equivalent to what the
+ * caller passed.
+ *
+ * @discussion
+ * The implementation will retry if the operation was interrupted by a signal.
+ * If the operation failed for any other reason, the implementation will
+ * terminate the caller.
+ */
+DARWIN_API_AVAILABLE_20180727
+OS_EXPORT OS_WARN_RESULT
+os_fd_t
+dup_np(os_fd_t fd);
+
+/*!
+ * @function claimfd_np
+ * Claims the given file descriptor for the caller's exclusive use by applying a
+ * guard and invalidating the given storage.
+ *
+ * @param fdp
+ * A pointer to the storage for the descriptor to claim. Upon return, a known-
+ * invalid value is written into this memory.
+ *
+ * @param gdid
+ * The optional guard value to enforce the caller's claim on the descriptor.
+ *
+ * @param gdflags
+ * The guard flags to enforce the caller's claim on the descriptor.
+ *
+ * @result
+ * The given descriptor with the guard applied.
+ */
+DARWIN_API_AVAILABLE_20190830
+OS_EXPORT OS_WARN_RESULT OS_NONNULL1
+os_fd_t
+claimfd_np(os_fd_t *fdp, const guardid_t *gdid, u_int gdflags);
+
+/*!
+ * @function xferfd_np
+ * Transfers ownership from the given file descriptor back to the general public
+ * by clearing the guard associated with it.
+ *
+ * @param fdp
+ * A pointer to the storage for the descriptor to claim. Upon return, a known-
+ * invalid value is written into this memory.
+ *
+ * @param gdid
+ * The optional guard value to reliquish ownership on the descriptor.
+ *
+ * @param gdflags
+ * The guard flags to relinquish.
+ *
+ * @result
+ * The given descriptor with the guard cleared. This descriptor is suitable for
+ * claiming with {@link claimfd_np}.
+ */
+DARWIN_API_AVAILABLE_20190830
+OS_EXPORT OS_WARN_RESULT OS_NONNULL1
+os_fd_t
+xferfd_np(os_fd_t *fdp, const guardid_t *gdid, u_int gdflags);
+
+/*!
+ * @function close_drop_np
+ * Variant of close(2) which transfers ownership from the caller and performs
+ * the close(2) operation. These semantics are useful for ensuring that a
+ * descriptor is not erroneously re-used after it has been closed. To achieve
+ * these semantics, this variant will clear the memory in which the descriptor
+ * resides and replace it with a known-invalid value before returning.
+ *
+ * @param fdp
+ * A pointer to the storage for the descriptor to close. Upon return, a known-
+ * invalid value is written into this memory.
+ *
+ * @param gdid
+ * The optional guard. If the descriptor is not guarded, pass NULL.
+ *
+ * @discussion
+ * If the implementation encounters a failure to close a valid descriptor
+ * number, the caller will be terminated.
+ */
+OS_EXPORT OS_NONNULL1
+void
+close_drop_np(os_fd_t *fdp, const guardid_t *gdid);
+
+/*!
+ * @function close_drop_optional_np
+ * Variant of {@link close_drop} which will not attempt to close an invalid
+ * descriptor. Otherwise all semantics are the same.
+ *
+ * @param fdp
+ * A pointer to the storage for the descriptor to close. Upon return, a known-
+ * invalid value is written into this memory.
+ *
+ * @param gdid
+ * The optional guard. If the descriptor is not guarded, pass NULL.
+ *
+ * @discussion
+ * If the implementation encounters a failure to close a valid descriptor
+ * number, the caller will be terminated. The implementation will not attempt to
+ * close the descriptor if its value is -1.
+ */
+OS_EXPORT OS_NONNULL1
+void
+close_drop_optional_np(os_fd_t *fdp, const guardid_t *gdid);
+

 /*!
  * @function zsnprintf_np
  * snprintf(3) variant which returns the numnber of bytes written less the null
 /*!
  * @function zsnprintf_np
  * snprintf(3) variant which returns the numnber of bytes written less the null


@@ -74,6 +271,124 @@ OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3 OS_FORMAT_PRINTF(3, 4)
 size_t
 zsnprintf_np(char *buff, size_t len, const char *fmt, ...);
 
 size_t
 zsnprintf_np(char *buff, size_t len, const char *fmt, ...);
 

+/*!
+ * @function crfprintf_np
+ * fprintf(3) variant that appends a new line character to the output.
+ *
+ * @param f
+ * The file to which the output should be written.
+ *
+ * @param fmt
+ * The printf(3)-like format string.
+ *
+ * @param ...
+ * The arguments corresponding to the format string.
+ */
+DARWIN_API_AVAILABLE_20181020
+OS_EXPORT OS_NONNULL1 OS_NONNULL2 OS_FORMAT_PRINTF(2, 3)
+void
+crfprintf_np(FILE *f, const char *fmt, ...);
+
+/*!
+ * @function vcrfprintf_np
+ * vfprintf(3) variant that appends a new line character to the output.
+ *
+ * @param f
+ * The file to which the output should be written.
+ *
+ * @param fmt
+ * The printf(3)-like format string.
+ *
+ * @param ap
+ * The argument list corresponding to the format string.
+ */
+DARWIN_API_AVAILABLE_20181020
+OS_EXPORT OS_NONNULL1 OS_NONNULL2 OS_NONNULL3
+void
+vcrfprintf_np(FILE *f, const char *fmt, va_list ap);
+
+/*!
+ * @function wfprintf_np
+ * fprintf(3) variant which wraps the output to the specified column width,
+ * inserting new lines as necessary. Output will be word-wrapped with a trivial
+ * algorithm.
+ *
+ * @param f
+ * The file to which the output should be written.
+ *
+ * @param initpad
+ * The number of spaces that should be inserted prior to the first line of
+ * output. If a negative value is given, the implementation will assume that an
+ * amount of spaces equal to the absolute value of the parameter has already
+ * been written, and therefore it will only use the parameter to compute line-
+ * wrapping information and not insert any additional spaces on the first line
+ * of output.
+ *
+ * @param pad
+ * The number of spaces that should be inserted prior to every line of output
+ * except the first line.
+ *
+ * @param width
+ * The maximum number of columns of each line of output. Pass zero to indicate
+ * that there is no maximum.
+ *
+ * @param fmt
+ * The printf(3)-like format string.
+ *
+ * @param ...
+ * The arguments corresponding to the format string.
+ *
+ * @discussion
+ * This routine will silently fail to print to the desired output stream if
+ * there was a failure to allocate heap memory.
+ */
+DARWIN_API_AVAILABLE_20181020
+OS_EXPORT OS_NONNULL1 OS_NONNULL5 OS_NONNULL6
+void
+wfprintf_np(FILE *f, ssize_t initpad, size_t pad, size_t width,
+               const char *fmt, ...);
+
+/*!
+ * @function vwfprintf_np
+ * vfprintf(3) variant which wraps the output to the specified column width,
+ * inserting new lines as necessary. Output will be word-wrapped with a trivial
+ * algorithm.
+ *
+ * @param f
+ * The file to which the output should be written.
+ *
+ * @param initpad
+ * The number of spaces that should be inserted prior to the first line of
+ * output. If a negative value is given, the implementation will assume that an
+ * amount of spaces equal to the absolute value of the parameter has already
+ * been written, and therefore it will only use the parameter to compute line-
+ * wrapping information and not insert any additional spaces on the first line
+ * of output.
+ *
+ * @param pad
+ * The number of spaces that should be inserted prior to every line of output
+ * except the first line.
+ *
+ * @param width
+ * The maximum number of columns of each line of output. Pass zero to indicate
+ * that there is no maximum.
+ *
+ * @param fmt
+ * The printf(3)-like format string.
+ *
+ * @param ap
+ * The argument list corresponding to the format string.
+ *
+ * @discussion
+ * This routine will silently fail to print to the desired output stream if
+ * there was a failure to allocate heap memory.
+ */
+DARWIN_API_AVAILABLE_20181020
+OS_EXPORT OS_NONNULL1 OS_NONNULL5 OS_NONNULL6
+void
+vwfprintf_np(FILE *f, ssize_t initpad, size_t pad, size_t width,
+               const char *fmt, va_list ap);
+

 __END_DECLS;
 
 #endif // __DARWIN_STDIO_H
 __END_DECLS;
 
 #endif // __DARWIN_STDIO_H