man3/sockatmark.3

   1 .\" Copyright (c) 2006, Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .TH SOCKATMARK 3 2021-03-22 "Linux" "Linux Programmer's Manual"
  26 .SH NAME
  27 sockatmark \- determine whether socket is at out-of-band mark
  28 .SH SYNOPSIS
  29 .nf
  30 .B #include <sys/socket.h>
  31 .PP
  32 .BI "int sockatmark(int " sockfd );
  33 .fi
  34 .PP
  35 .RS -4
  36 Feature Test Macro Requirements for glibc (see
  37 .BR feature_test_macros (7)):
  38 .RE
  39 .PP
  40 .BR sockatmark ():
  41 .nf
  42     _POSIX_C_SOURCE >= 200112L
  43 .fi
  44 .SH DESCRIPTION
  45 .BR sockatmark ()
  46 returns a value indicating whether or not the socket referred
  47 to by the file descriptor
  48 .I sockfd
  49 is at the out-of-band mark.
  50 If the socket is at the mark, then 1 is returned;
  51 if the socket is not at the mark, 0 is returned.
  52 This function does not remove the out-of-band mark.
  53 .SH RETURN VALUE
  54 A successful call to
  55 .BR sockatmark ()
  56 returns 1 if the socket is at the out-of-band mark, or 0 if it is not.
  57 On error, \-1 is returned and
  58 .I errno
  59 is set to indicate the error.
  60 .SH ERRORS
  61 .TP
  62 .B EBADF
  63 .I sockfd
  64 is not a valid file descriptor.
  65 .TP
  66 .B EINVAL
  67 .\" POSIX.1 says ENOTTY for this case
  68 .I sockfd
  69 is not a file descriptor to which
  70 .BR sockatmark ()
  71 can be applied.
  72 .SH VERSIONS
  73 .BR sockatmark ()
  74 was added to glibc in version 2.2.4.
  75 .SH ATTRIBUTES
  76 For an explanation of the terms used in this section, see
  77 .BR attributes (7).
  78 .ad l
  79 .nh
  80 .TS
  81 allbox;
  82 lbx lb lb
  83 l l l.
  84 Interface       Attribute       Value
  85 T{
  86 .BR sockatmark ()
  87 T}      Thread safety   MT-Safe
  88 .TE
  89 .hy
  90 .ad
  91 .sp 1
  92 .SH CONFORMING TO
  93 POSIX.1-2001, POSIX.1-2008.
  94 .SH NOTES
  95 If
  96 .BR sockatmark ()
  97 returns 1, then the out-of-band data can be read using the
  98 .B MSG_OOB
  99 flag of
 100 .BR recv (2).
 101 .PP
 102 Out-of-band data is supported only on some stream socket protocols.
 103 .PP
 104 .BR sockatmark ()
 105 can safely be called from a handler for the
 106 .B SIGURG
 107 signal.
 108 .PP
 109 .BR sockatmark ()
 110 is implemented using the
 111 .B SIOCATMARK
 112 .BR ioctl (2)
 113 operation.
 114 .SH BUGS
 115 Prior to glibc 2.4,
 116 .BR sockatmark ()
 117 did not work.
 118 .SH EXAMPLES
 119 The following code can be used after receipt of a
 120 .B SIGURG
 121 signal to read (and discard) all data up to the mark,
 122 and then read the byte of data at the mark:
 123 .PP
 124 .EX
 125     char buf[BUF_LEN];
 126     char oobdata;
 127     int atmark, s;
 128
 129     for (;;) {
 130         atmark = sockatmark(sockfd);
 131         if (atmark == \-1) {
 132             perror("sockatmark");
 133             break;
 134         }
 135
 136         if (atmark)
 137             break;
 138
 139         s = read(sockfd, buf, BUF_LEN);
 140         if (s == \-1)
 141             perror("read");
 142         if (s <= 0)
 143             break;
 144     }
 145
 146     if (atmark == 1) {
 147         if (recv(sockfd, &oobdata, 1, MSG_OOB) == \-1) {
 148             perror("recv");
 149             ...
 150         }
 151     }
 152 .EE
 153 .SH SEE ALSO
 154 .BR fcntl (2),
 155 .BR recv (2),
 156 .BR send (2),
 157 .BR tcp (7)