libdarwin/h/stdio.h

   1 /*
   2  * Copyright (c) 2018 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 /*!
  25  * @header
  26  * Non-standard, Darwin-specific additions for the stdio(3) family of APIs.
  27  */
  28 #ifndef __DARWIN_STDIO_H
  29 #define __DARWIN_STDIO_H
  30
  31 #include <os/base.h>
  32 #include <os/api.h>
  33 #include <sys/cdefs.h>
  34 #include <stdint.h>
  35 #include <stdbool.h>
  36 #include <unistd.h>
  37
  38 // TAPI and the compiler don't agree about header search paths, so if TAPI found
  39 // our header in the SDK, help it out.
  40 #if DARWIN_TAPI && DARWIN_API_VERSION < 20180727
  41 #define DARWIN_API_AVAILABLE_20180727
  42 #endif
  43
  44 __BEGIN_DECLS;
  45
  46 /*!
  47  * @typedef os_fd_t
  48  * A type alias for a file descriptor.
  49  */
  50 typedef int os_fd_t;
  51
  52 /*!
  53  * @function os_fd_valid
  54  * Returns whether the given integer is a valid file descriptor number.
  55  *
  56  * @param fd
  57  * The integer to check.
  58  *
  59  * @result
  60  * A Boolean indicating whether the integer is a valid file descriptor number,
  61  * that is, greater than or equal to zero.
  62  */
  63 DARWIN_API_AVAILABLE_20180727
  64 OS_ALWAYS_INLINE OS_WARN_RESULT
  65 static inline bool
  66 os_fd_valid(os_fd_t fd)
  67 {
  68         return (fd >= STDIN_FILENO);
  69 }
  70
  71 /*!
  72  * @function fcheck_np
  73  * Checks the status of an fread(3) or fwrite(3) operation to a FILE.
  74  *
  75  * @param f
  76  * The file on which the operation was performed.
  77  *
  78  * @param n
  79  * The return value of the operation.
  80  *
  81  * @param expected
  82  * The expected return value of the operation.
  83  *
  84  * @result
  85  * One of the following integers:
  86  *
  87  *     0     The operation succeeded
  88  *     EOF   The operation encountered the end of the FILE stream before it
  89  *           could complete
  90  *     1     There was an error
  91  */
  92 DARWIN_API_AVAILABLE_20180727
  93 OS_EXPORT OS_WARN_RESULT OS_NONNULL1
  94 int
  95 fcheck_np(FILE *f, size_t n, size_t expected);
  96
  97 /*!
  98  * @function dup_np
  99  * Variant of dup(2) that guarantees the dup(2) operation will either succeed or
 100  * not return.
 101  *
 102  * @param fd
 103  * The descriptor to dup(2).
 104  *
 105  * @result
 106  * A new file descriptor number that is functionally equivalent to what the
 107  * caller passed.
 108  *
 109  * @discussion
 110  * The implementation will retry if the operation was interrupted by a signal.
 111  * If the operation failed for any other reason, the implementation will
 112  * terminate the caller.
 113  */
 114 DARWIN_API_AVAILABLE_20180727
 115 OS_EXPORT OS_WARN_RESULT
 116 os_fd_t
 117 dup_np(os_fd_t fd);
 118
 119 /*!
 120  * @function zsnprintf_np
 121  * snprintf(3) variant which returns the numnber of bytes written less the null
 122  * terminator.
 123  *
 124  * @param buff
 125  * The buffer in which to write the string.
 126  *
 127  * @param len
 128  * The length of the buffer.
 129  *
 130  * @param fmt
 131  * The printf(3)-like format string.
 132  *
 133  * @param ...
 134  * The arguments corresponding to the format string.
 135  *
 136  * @result
 137  * The number of bytes written into the buffer, less the null terminator. This
 138  * routine is useful for successive string printing that may be lossy, as it
 139  * will simply return zero when there is no space left in the destination
 140  * buffer, i.e. enables the following pattern:
 141  *
 142  * char *cur = buff;
 143  * size_t left = sizeof(buff);
 144  * for (i = 0; i < n_strings; i++) {
 145  *     size_t n_written = zsnprintf_np(buff, left, "%s", strings[i]);
 146  *     cur += n_written;
 147  *     left -= n_written;
 148  * }
 149  *
 150  * This loop will safely terminate without any special care since, as soon as
 151  * the buffer's space is exhausted, all further calls to zsnprintf_np() will
 152  * write nothing and return zero.
 153  */
 154 DARWIN_API_AVAILABLE_20170407
 155 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3 OS_FORMAT_PRINTF(3, 4)
 156 size_t
 157 zsnprintf_np(char *buff, size_t len, const char *fmt, ...);
 158
 159 /*!
 160  * @function crfprintf_np
 161  * fprintf(3) variant that appends a new line character to the output.
 162  *
 163  * @param f
 164  * The file to which the output should be written.
 165  *
 166  * @param fmt
 167  * The printf(3)-like format string.
 168  *
 169  * @param ...
 170  * The arguments corresponding to the format string.
 171  */
 172 DARWIN_API_AVAILABLE_20181020
 173 OS_EXPORT OS_NONNULL1 OS_NONNULL2 OS_FORMAT_PRINTF(2, 3)
 174 void
 175 crfprintf_np(FILE *f, const char *fmt, ...);
 176
 177 /*!
 178  * @function vcrfprintf_np
 179  * vfprintf(3) variant that appends a new line character to the output.
 180  *
 181  * @param f
 182  * The file to which the output should be written.
 183  *
 184  * @param fmt
 185  * The printf(3)-like format string.
 186  *
 187  * @param ap
 188  * The argument list corresponding to the format string.
 189  */
 190 DARWIN_API_AVAILABLE_20181020
 191 OS_EXPORT OS_NONNULL1 OS_NONNULL2 OS_NONNULL3
 192 void
 193 vcrfprintf_np(FILE *f, const char *fmt, va_list ap);
 194
 195 /*!
 196  * @function wfprintf_np
 197  * fprintf(3) variant which wraps the output to the specified column width,
 198  * inserting new lines as necessary. Output will be word-wrapped with a trivial
 199  * algorithm.
 200  *
 201  * @param f
 202  * The file to which the output should be written.
 203  *
 204  * @param initpad
 205  * The number of spaces that should be inserted prior to the first line of
 206  * output. If a negative value is given, the implementation will assume that an
 207  * amount of spaces equal to the absolute value of the parameter has already
 208  * been written, and therefore it will only use the parameter to compute line-
 209  * wrapping information and not insert any additional spaces on the first line
 210  * of output.
 211  *
 212  * @param pad
 213  * The number of spaces that should be inserted prior to every line of output
 214  * except the first line.
 215  *
 216  * @param width
 217  * The maximum number of columns of each line of output. Pass zero to indicate
 218  * that there is no maximum.
 219  *
 220  * @param fmt
 221  * The printf(3)-like format string.
 222  *
 223  * @param ...
 224  * The arguments corresponding to the format string.
 225  *
 226  * @discussion
 227  * This routine will silently fail to print to the desired output stream if
 228  * there was a failure to allocate heap memory.
 229  */
 230 DARWIN_API_AVAILABLE_20181020
 231 OS_EXPORT OS_NONNULL1 OS_NONNULL5 OS_NONNULL6
 232 void
 233 wfprintf_np(FILE *f, ssize_t initpad, size_t pad, size_t width,
 234                 const char *fmt, ...);
 235
 236 /*!
 237  * @function vwfprintf_np
 238  * vfprintf(3) variant which wraps the output to the specified column width,
 239  * inserting new lines as necessary. Output will be word-wrapped with a trivial
 240  * algorithm.
 241  *
 242  * @param f
 243  * The file to which the output should be written.
 244  *
 245  * @param initpad
 246  * The number of spaces that should be inserted prior to the first line of
 247  * output. If a negative value is given, the implementation will assume that an
 248  * amount of spaces equal to the absolute value of the parameter has already
 249  * been written, and therefore it will only use the parameter to compute line-
 250  * wrapping information and not insert any additional spaces on the first line
 251  * of output.
 252  *
 253  * @param pad
 254  * The number of spaces that should be inserted prior to every line of output
 255  * except the first line.
 256  *
 257  * @param width
 258  * The maximum number of columns of each line of output. Pass zero to indicate
 259  * that there is no maximum.
 260  *
 261  * @param fmt
 262  * The printf(3)-like format string.
 263  *
 264  * @param ap
 265  * The argument list corresponding to the format string.
 266  *
 267  * @discussion
 268  * This routine will silently fail to print to the desired output stream if
 269  * there was a failure to allocate heap memory.
 270  */
 271 DARWIN_API_AVAILABLE_20181020
 272 OS_EXPORT OS_NONNULL1 OS_NONNULL5 OS_NONNULL6
 273 void
 274 vwfprintf_np(FILE *f, ssize_t initpad, size_t pad, size_t width,
 275                 const char *fmt, va_list ap);
 276
 277 __END_DECLS;
 278
 279 #endif // __DARWIN_STDIO_H