PROLOG

       This  manual  page  is part of the POSIX Programmer's Manual.  The Linux implementation of
       this interface may differ (consult the corresponding Linux  manual  page  for  details  of
       Linux behavior), or the interface may not be implemented on Linux.

NAME

       sockatmark — determine whether a socket is at the out-of-band mark

SYNOPSIS

       #include <sys/socket.h>

       int sockatmark(int s);

DESCRIPTION

       The sockatmark() function shall determine whether the socket specified by the descriptor s
       is at the out-of-band data mark (see Section 2.10.12, Socket Out-of-Band Data State).   If
       the  protocol  for the socket supports out-of-band data by marking the stream with an out-
       of-band data mark, the sockatmark() function shall return 1 when all  data  preceding  the
       mark  has  been  read  and  the  out-of-band data mark is the first element in the receive
       queue. The sockatmark() function shall not remove the mark from the stream.

RETURN VALUE

       Upon successful completion, the sockatmark() function  shall  return  a  value  indicating
       whether  the  socket  is  at an out-of-band data mark. If the protocol has marked the data
       stream and all data preceding the mark has been read, the return  value  shall  be  1;  if
       there  is  no  mark,  or  if data precedes the mark in the receive queue, the sockatmark()
       function shall return 0. Otherwise, it shall return  a  value  of  −1  and  set  errno  to
       indicate the error.

ERRORS

       The sockatmark() function shall fail if:

       EBADF  The s argument is not a valid file descriptor.

       ENOTTY The file associated with the s argument is not a socket.

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       The  use  of  this  function between receive operations allows an application to determine
       which received data precedes the out-of-band data and which follows the out-of-band data.

       There is an inherent race condition in the use of  this  function.  On  an  empty  receive
       queue,  the current read of the location might well be at the ``mark'', but the system has
       no way of knowing that the next data segment that will arrive from the network will  carry
       the  mark,  and  sockatmark() will return false, and the next read operation will silently
       consume the mark.

       Hence, this function can only be used reliably when the application already knows that the
       out-of-band  data  has  been  seen  by  the  system or that it is known that there is data
       waiting to be read at the socket (via SIGURG or select()).  See  Section  2.10.11,  Socket
       Receive  Queue,  Section 2.10.12, Socket Out-of-Band Data State, Section 2.10.14, Signals,
       and pselect() for details.

RATIONALE

       The sockatmark() function replaces the historical  SIOCATMARK  command  to  ioctl()  which
       implemented  the  same  functionality  on  many  implementations. Using a wrapper function
       follows the adopted conventions to avoid specifying  commands  to  the  ioctl()  function,
       other  than  those now included to support XSI STREAMS. The sockatmark() function could be
       implemented as follows:

           #include <sys/ioctl.h>

           int sockatmark(int s)
           {
               int val;
               if (ioctl(s,SIOCATMARK,&val)==−1)
                   return(−1);
               return(val);
           }

       The use of [ENOTTY] to indicate  an  incorrect  descriptor  type  matches  the  historical
       behavior of SIOCATMARK.

FUTURE DIRECTIONS

       None.

SEE ALSO

       Section 2.10.12, Socket Out-of-Band Data State, pselect(), recv(), recvmsg()

       The Base Definitions volume of POSIX.1‐2008, <sys_socket.h>

COPYRIGHT

       Portions  of  this  text  are  reprinted  and  reproduced in electronic form from IEEE Std
       1003.1, 2013 Edition, Standard for Information Technology  --  Portable  Operating  System
       Interface  (POSIX),  The Open Group Base Specifications Issue 7, Copyright (C) 2013 by the
       Institute of Electrical and Electronics Engineers, Inc  and  The  Open  Group.   (This  is
       POSIX.1-2008  with  the  2013  Technical  Corrigendum  1  applied.)  In  the  event of any
       discrepancy between this version and the original IEEE and The Open  Group  Standard,  the
       original  IEEE  and The Open Group Standard is the referee document. The original Standard
       can be obtained online at http://www.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are most  likely  to  have
       been  introduced  during  the conversion of the source files to man page format. To report
       such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .