1.\" Copyright (c) 2002 William C. Fenner. All rights reserved. 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions 5.\" are met: 6.\" 1. Redistributions of source code must retain the above copyright 7.\" notice, this list of conditions and the following disclaimer. 8.\" 2. Redistributions in binary form must reproduce the above copyright 9.\" notice, this list of conditions and the following disclaimer in the 10.\" documentation and/or other materials provided with the distribution. 11.\" 12.\" THIS SOFTWARE IS PROVIDED BY THE CONTRIBUTORS ``AS IS'' AND 13.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 14.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 15.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 16.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 17.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 18.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 19.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 20.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 21.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 22.\" SUCH DAMAGE. 23.\" 24.\" $FreeBSD$ 25.\" 26.Dd July 3, 2022 27.Dt SOCKATMARK 3 28.Os 29.Sh NAME 30.Nm sockatmark 31.Nd determine whether the read pointer is at the OOB mark 32.Sh LIBRARY 33.Lb libc 34.Sh SYNOPSIS 35.In sys/socket.h 36.Ft int 37.Fn sockatmark "int s" 38.Sh DESCRIPTION 39To find out if the read pointer is currently pointing at 40the mark in the data stream, the 41.Fn sockatmark 42function is provided. 43If 44.Fn sockatmark 45returns 1, the next read will return data 46after the mark. 47Otherwise (assuming out of band data has arrived), 48the next read will provide data sent by the client prior 49to transmission of the out of band signal. 50The routine used 51in the remote login process to flush output on receipt of an 52interrupt or quit signal is shown below. 53It reads the normal data up to the mark (to discard it), 54then reads the out-of-band byte. 55.Bd -literal -offset indent 56#include <sys/socket.h> 57\&... 58oob() 59{ 60 int out = FWRITE, mark; 61 char waste[BUFSIZ]; 62 63 /* flush local terminal output */ 64 ioctl(1, TIOCFLUSH, (char *)&out); 65 for (;;) { 66 if ((mark = sockatmark(rem)) < 0) { 67 perror("sockatmark"); 68 break; 69 } 70 if (mark) 71 break; 72 (void) read(rem, waste, sizeof (waste)); 73 } 74 if (recv(rem, &mark, 1, MSG_OOB) < 0) { 75 perror("recv"); 76 ... 77 } 78 ... 79} 80.Ed 81.Sh RETURN VALUES 82Upon successful completion, the 83.Fn sockatmark 84function returns the value 1 if the read pointer is pointing at 85the OOB mark, 0 if it is not. 86Otherwise the value \-1 is returned 87and the global variable 88.Va errno 89is set to 90indicate the error. 91.Sh ERRORS 92The 93.Fn sockatmark 94call fails if: 95.Bl -tag -width Er 96.It Bq Er EBADF 97The 98.Fa s 99argument 100is not a valid descriptor. 101.It Bq Er ENOTTY 102The 103.Fa s 104argument 105is a descriptor for a file, not a socket. 106.El 107.Sh SEE ALSO 108.Xr recv 2 , 109.Xr send 2 110.Rs 111.%T "An Introductory 4.4BSD Interprocess Communication Tutorial" 112.%A Stuart Sechrest 113.Re 114.%U https://docs.freebsd.org/44doc/psd/20.ipctut/paper.pdf 115.Rs 116.%T "An Advanced 4.4BSD Interprocess Communication Tutorial" 117.%A Samuel J. Leffler 118.%A Robert S. Fabry 119.%A William N. Joy 120.%A Phil Lapsley 121.%A Steve Miller 122.%A Chris Torek 123.%U https://docs.freebsd.org/44doc/psd/21.ipc/paper.pdf 124.Re 125.Sh HISTORY 126The 127.Fn sockatmark 128function was introduced by 129.St -p1003.1-2001 , 130to standardize the historical 131.Dv SIOCATMARK 132.Xr ioctl 2 . 133The 134.Er ENOTTY 135error instead of the usual 136.Er ENOTSOCK 137is to match the historical behavior of 138.Dv SIOCATMARK . 139