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 .PP
  16 .BI "int sockatmark(int " sockfd );
  17 .fi
  18 .PP
  19 .RS -4
  20 Feature Test Macro Requirements for glibc (see
  21 .BR feature_test_macros (7)):
  22 .RE
  23 .PP
  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 .sp 1
  71 .SH STANDARDS
  72 POSIX.1-2008.
  73 .SH HISTORY
  74 glibc 2.2.4.
  75 POSIX.1-2001.
  76 .SH NOTES
  77 If
  78 .BR sockatmark ()
  79 returns 1, then the out-of-band data can be read using the
  80 .B MSG_OOB
  81 flag of
  82 .BR recv (2).
  83 .PP
  84 Out-of-band data is supported only on some stream socket protocols.
  85 .PP
  86 .BR sockatmark ()
  87 can safely be called from a handler for the
  88 .B SIGURG
  89 signal.
  90 .PP
  91 .BR sockatmark ()
  92 is implemented using the
  93 .B SIOCATMARK
  94 .BR ioctl (2)
  95 operation.
  96 .SH BUGS
  97 Prior to glibc 2.4,
  98 .BR sockatmark ()
  99 did not work.
 100 .SH EXAMPLES
 101 The following code can be used after receipt of a
 102 .B SIGURG
 103 signal to read (and discard) all data up to the mark,
 104 and then read the byte of data at the mark:
 105 .PP
 106 .EX
 107     char buf[BUF_LEN];
 108     char oobdata;
 109     int atmark, s;
 110 \&
 111     for (;;) {
 112         atmark = sockatmark(sockfd);
 113         if (atmark == \-1) {
 114             perror("sockatmark");
 115             break;
 116         }
 117 \&
 118         if (atmark)
 119             break;
 120 \&
 121         s = read(sockfd, buf, BUF_LEN);
 122         if (s == \-1)
 123             perror("read");
 124         if (s <= 0)
 125             break;
 126     }
 127 \&
 128     if (atmark == 1) {
 129         if (recv(sockfd, &oobdata, 1, MSG_OOB) == \-1) {
 130             perror("recv");
 131             ...
 132         }
 133     }
 134 .EE
 135 .SH SEE ALSO
 136 .BR fcntl (2),
 137 .BR recv (2),
 138 .BR send (2),
 139 .BR tcp (7)