lib/libc/sockatmark.3

   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 .\" From FreeBSD: r108087 2002-12-19 01:40:28 -0800
  25 .\" $OpenBSD: sockatmark.3,v 1.1 2014/08/31 02:27:37 guenther Exp $
  26 .\"
  27 .Dd October 26, 2016
  28 .Dt SOCKATMARK 3
  29 .Os
  30 .Sh NAME
  31 .Nm sockatmark
  32 .Nd determine whether the read pointer is at the out-of-band data mark
  33 .Sh SYNOPSIS
  34 .In sys/socket.h
  35 .Ft int
  36 .Fn sockatmark "int s"
  37 .Sh DESCRIPTION
  38 The
  39 .Fn sockatmark
  40 function returns 1 if the read pointer for the socket
  41 .Fa s
  42 is currently at the out-of-band data mark.
  43 Otherwise, it returns 0 if the socket doesn't have an out-of-band
  44 data mark or if there is normal data to be received before the mark.
  45 .Sh RETURN VALUES
  46 Upon successful completion, the
  47 .Fn sockatmark
  48 function returns the value 1 if the read pointer is pointing at
  49 the out-of-band data mark, 0 if it is not.
  50 Otherwise the value \-1 is returned
  51 and the global variable
  52 .Va errno
  53 is set to
  54 indicate the error.
  55 .Sh EXAMPLES
  56 The routine used in the historical remote login process to flush
  57 output on receipt of an interrupt or quit signal is shown below.
  58 It reads the normal data up to the mark (to discard it),
  59 then reads the out-of-band byte.
  60 .Bd -literal -offset indent
  61 #include <sys/socket.h>
  62 \&...
  63 oob()
  64 {
  65         int mark;
  66         char waste[BUFSIZ];
  67
  68         for (;;) {
  69                 if ((mark = sockatmark(rem)) < 0) {
  70                         perror("sockatmark");
  71                         break;
  72                 }
  73                 if (mark)
  74                         break;
  75                 (void) read(rem, waste, sizeof (waste));
  76         }
  77         if (recv(rem, &mark, 1, MSG_OOB) < 0) {
  78                 perror("recv");
  79                 ...
  80         }
  81         ...
  82 }
  83 .Ed
  84 .Sh ERRORS
  85 The
  86 .Fn sockatmark
  87 call fails if:
  88 .Bl -tag -width Er
  89 .It Bq Er EBADF
  90 .Fa s
  91 is not a valid descriptor.
  92 .It Bq Er ENOTTY
  93 .Fa s
  94 is valid but does not refer to a socket.
  95 .El
  96 .Sh SEE ALSO
  97 .Xr recv 2 ,
  98 .Xr send 2
  99 .Sh STANDARDS
 100 The
 101 .Fn sockatmark
 102 function conforms to
 103 .St -p1003.1-2008 .
 104 .Sh HISTORY
 105 The
 106 .Fn sockatmark
 107 function was introduced by
 108 .St -p1003.1-2001
 109 to standardize the historical
 110 .Dv SIOCATMARK
 111 .Xr ioctl 2 .
 112 .Pp
 113 The
 114 .Er ENOTTY
 115 error is returned instead of the usual
 116 .Er ENOTSOCK
 117 error to match the historical behavior of
 118 .Dv SIOCATMARK .