1.\" $OpenBSD: __fpending.3,v 1.2 2024/08/12 21:27:57 tb Exp $ 2.\" 3.\" Copyright (c) 2024 Philip Guenther <guenther@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: August 12 2024 $ 18.Dt __FPENDING 3 19.Os 20.Sh NAME 21.Nm __fpending , 22.Nm __freadahead , 23.Nm __freading , 24.Nm __freadptr , 25.Nm __freadptrinc , 26.Nm __fseterr , 27.Nm __fwriting 28.Nd stream extension functions 29.Sh SYNOPSIS 30.In stdio_ext.h 31.Ft size_t 32.Fn __fpending "FILE *stream" 33.Ft size_t 34.Fn __freadahead "FILE *stream" 35.Ft int 36.Fn __freading "FILE *stream" 37.Ft "const char *" 38.Fn __freadptr "FILE *stream" "size_t *sizep" 39.Ft void 40.Fn __freadptrinc "FILE *stream" "size_t increment" 41.Ft void 42.Fn __fseterr "FILE *stream" 43.Ft int 44.Fn __fwriting "FILE *stream" 45.Sh DESCRIPTION 46The 47.Fn __fpending 48function returns the number of bytes of output data currently 49buffered on 50.Fa stream . 51.Pp 52The 53.Fn __freadahead 54function returns the number of bytes of input data currently 55buffered on 56.Fa stream . 57.Pp 58The 59.Fn __freading 60function returns non-zero if 61.Fa stream 62either was opened read-only or if the last operation on the stream 63was a read or push-back operation. 64.Pp 65The 66.Fn __freadptr 67function returns either a pointer to the next byte of buffered input 68data on 69.Fa stream 70and stores the number of consecutive bytes of buffered data available 71to the location pointed to by 72.Fa sizep , 73or return 74.Dv NULL 75if there's no buffered input data. 76The value returned via 77.Fa sizep 78may differ from the value that would be returned by 79.Fn __freadahead . 80.Pp 81The 82.Fn __freadptrinc 83function consumes 84.Fa increment 85bytes of buffered input data on 86.Fa stream . 87This is only valid immediately after a non-NULL return from 88.Fn __freadptr 89and 90.Fa increment 91must not be greater than the size value from that call. 92.Pp 93The 94.Fn __fseterr 95function sets the error indicator for 96.Fa stream . 97.Pp 98The 99.Fn __fwriting 100function returns non-zero if 101.Fa stream 102either was opened write-only or append-only or if the last operation 103on the stream was a write operation. 104.Sh ERRORS 105These functions should not fail and do not set the external 106variable 107.Va errno . 108.Sh SEE ALSO 109.Xr fflush 3 110.Sh HISTORY 111The 112.Fn __fpending , 113.Fn __freadahead , 114.Fn __freading , 115.Fn __freadptr , 116.Fn __freadptrinc , 117.Fn __fseterr , 118and 119.Fn __fwriting 120functions appeared in 121.Ox 7.6 . 122.Sh BUGS 123These functions are under-specified and non-portable. 124They exist to permit a particular 125.Dq portability 126library to function without direct manipulation of stdio structures; 127everyone else should either implement their own stdio layer, 128do the work of defining and standardizing the required functionality, 129or reconsider their life decisions. 130