Unix/Linux Go Back    


Linux 2.6 - man page for sockatmark (linux section 3posix)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


SOCKATMARK(P)			    POSIX Programmer's Manual			    SOCKATMARK(P)

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 the System Interfaces volume of IEEE Std 1003.1-2001,
       Section	2.10.12,  Socket Out-of-Band 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()  func-
       tion  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 indi-
       cate the error.

ERRORS
       The sockatmark() function shall fail if:

       EBADF  The s argument is not a valid file descriptor.

       ENOTTY The s argument does not specify a descriptor for 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  con-
       sume 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  wait-
       ing  to	be read at the socket (via SIGURG or select()). See Socket Receive Queue , Socket
       Out-of-Band Data State , 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 fol-
       lows 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 imple-
       mented 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 behav-
       ior of SIOCATMARK.

FUTURE DIRECTIONS
       None.

SEE ALSO
       pselect()  ,  recv()  ,	recvmsg()  , the Base Definitions volume of IEEE Std 1003.1-2001,
       <sys/socket.h>

COPYRIGHT
       Portions of this text are reprinted and	reproduced  in	electronic  form  from	IEEE  Std
       1003.1,	2003  Edition,	Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003  by
       the  Institute  of  Electrical  and  Electronics Engineers, Inc and The Open Group. 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 orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003				    SOCKATMARK(P)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 09:58 PM.