man3/sockatmark.3

   1 '\" t
   2 .\" Copyright (c) 2006, Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .TH sockatmark 3 (date) "Linux man-pages (unreleased)"
   7 .SH NAME
   8 sockatmark \- determine whether socket is at out-of-band mark
   9 .SH LIBRARY
  10 Standard C library
  11 .RI ( libc ", " \-lc )
  12 .SH SYNOPSIS
  13 .nf
  14 .B #include <sys/socket.h>
  15 .P
  16 .BI "int sockatmark(int " sockfd );
  17 .fi
  18 .P
  19 .RS -4
  20 Feature Test Macro Requirements for glibc (see
  21 .BR feature_test_macros (7)):
  22 .RE
  23 .P
  24 .BR sockatmark ():
  25 .nf
  26     _POSIX_C_SOURCE >= 200112L
  27 .fi
  28 .SH DESCRIPTION
  29 .BR sockatmark ()
  30 returns a value indicating whether or not the socket referred
  31 to by the file descriptor
  32 .I sockfd
  33 is at the out-of-band mark.
  34 If the socket is at the mark, then 1 is returned;
  35 if the socket is not at the mark, 0 is returned.
  36 This function does not remove the out-of-band mark.
  37 .SH RETURN VALUE
  38 A successful call to
  39 .BR sockatmark ()
  40 returns 1 if the socket is at the out-of-band mark, or 0 if it is not.
  41 On error, \-1 is returned and
  42 .I errno
  43 is set to indicate the error.
  44 .SH ERRORS
  45 .TP
  46 .B EBADF
  47 .I sockfd
  48 is not a valid file descriptor.
  49 .TP
  50 .B EINVAL
  51 .\" POSIX.1 says ENOTTY for this case
  52 .I sockfd
  53 is not a file descriptor to which
  54 .BR sockatmark ()
  55 can be applied.
  56 .SH ATTRIBUTES
  57 For an explanation of the terms used in this section, see
  58 .BR attributes (7).
  59 .TS
  60 allbox;
  61 lbx lb lb
  62 l l l.
  63 Interface       Attribute       Value
  64 T{
  65 .na
  66 .nh
  67 .BR sockatmark ()
  68 T}      Thread safety   MT-Safe
  69 .TE
  70 .SH STANDARDS
  71 POSIX.1-2008.
  72 .SH HISTORY
  73 glibc 2.2.4.
  74 POSIX.1-2001.
  75 .SH NOTES
  76 If
  77 .BR sockatmark ()
  78 returns 1, then the out-of-band data can be read using the
  79 .B MSG_OOB
  80 flag of
  81 .BR recv (2).
  82 .P
  83 Out-of-band data is supported only on some stream socket protocols.
  84 .P
  85 .BR sockatmark ()
  86 can safely be called from a handler for the
  87 .B SIGURG
  88 signal.
  89 .P
  90 .BR sockatmark ()
  91 is implemented using the
  92 .B SIOCATMARK
  93 .BR ioctl (2)
  94 operation.
  95 .SH BUGS
  96 Prior to glibc 2.4,
  97 .BR sockatmark ()
  98 did not work.
  99 .SH EXAMPLES
 100 The following code can be used after receipt of a
 101 .B SIGURG
 102 signal to read (and discard) all data up to the mark,
 103 and then read the byte of data at the mark:
 104 .P
 105 .EX
 106     char buf[BUF_LEN];
 107     char oobdata;
 108     int atmark, s;
 109 \&
 110     for (;;) {
 111         atmark = sockatmark(sockfd);
 112         if (atmark == \-1) {
 113             perror("sockatmark");
 114             break;
 115         }
 116 \&
 117         if (atmark)
 118             break;
 119 \&
 120         s = read(sockfd, buf, BUF_LEN);
 121         if (s == \-1)
 122             perror("read");
 123         if (s <= 0)
 124             break;
 125     }
 126 \&
 127     if (atmark == 1) {
 128         if (recv(sockfd, &oobdata, 1, MSG_OOB) == \-1) {
 129             perror("recv");
 130             ...
 131         }
 132     }
 133 .EE
 134 .SH SEE ALSO
 135 .BR fcntl (2),
 136 .BR recv (2),
 137 .BR send (2),
 138 .BR tcp (7)