# sockatmark

## 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.
    


* * *