lib/libc/sys/shutdown.2

   1 .\" Copyright (c) 2007 Bruce M. Simpson.
   2 .\" Copyright (c) 1983, 1991, 1993
   3 .\"     The Regents of the University of California.  All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 4. Neither the name of the University nor the names of its contributors
  14 .\"    may be used to endorse or promote products derived from this software
  15 .\"    without specific prior written permission.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\"     @(#)shutdown.2  8.1 (Berkeley) 6/4/93
  30 .\" $FreeBSD$
  31 .\"
  32 .Dd March 5, 2007
  33 .Dt SHUTDOWN 2
  34 .Os
  35 .Sh NAME
  36 .Nm shutdown
  37 .Nd disable sends and/or receives on a socket
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In sys/types.h
  42 .In sys/socket.h
  43 .Ft int
  44 .Fn shutdown "int s" "int how"
  45 .Sh DESCRIPTION
  46 The
  47 .Fn shutdown
  48 system call disables sends or receives on a socket.
  49 The
  50 .Fa how
  51 argument specifies the type of shutdown.
  52 Possible values are:
  53 .Bl -tag -width ".Dv SHUT_RDWR"
  54 .It Dv SHUT_RD
  55 Further receives will be disallowed.
  56 .It Dv SHUT_WR
  57 Further sends will be disallowed.
  58 This may cause actions specific to the protocol family of the socket
  59 .Fa s
  60 to happen; see
  61 .Sx IMPLEMENTATION NOTES .
  62 .It Dv SHUT_RDWR
  63 Further sends and receives will be disallowed.
  64 Implies
  65 .Dv SHUT_WR .
  66 .El
  67 .Pp
  68 If the file descriptor
  69 .Fa s
  70 is associated with a
  71 .Dv SOCK_STREAM
  72 socket, all or part of the full-duplex connection will be shut down.
  73 .\"
  74 .Sh IMPLEMENTATION NOTES
  75 The following protocol specific actions apply to the use of
  76 .Dv SHUT_WR
  77 (and potentially also
  78 .Dv SHUT_RDWR ) ,
  79 based on the properties of the socket associated with the file descriptor
  80 .Fa s .
  81 .Bl -column ".Dv PF_INET6" ".Dv SOCK_STREAM" ".Dv IPPROTO_SCTP"
  82 .It Sy Domain Ta Sy Type Ta Sy Protocol Ta Sy Return value and action
  83 .It Dv PF_INET Ta Dv SOCK_DGRAM Ta Dv IPPROTO_SCTP Ta
  84 Return \-1.
  85 The global variable
  86 .Va errno
  87 will be set to
  88 .Er EOPNOTSUPP .
  89 .It Dv PF_INET Ta Dv SOCK_DGRAM Ta Dv IPPROTO_UDP Ta
  90 Return 0.
  91 ICMP messages will
  92 .Em not
  93 be generated.
  94 .It Dv PF_INET Ta Dv SOCK_STREAM Ta Dv IPPROTO_SCTP Ta
  95 Return 0.
  96 Send queued data and tear down association.
  97 .It Dv PF_INET Ta Dv SOCK_STREAM Ta Dv IPPROTO_TCP Ta
  98 Return 0.
  99 Send queued data, wait for ACK, then send FIN.
 100 .It Dv PF_INET6 Ta Dv SOCK_DGRAM Ta Dv IPPROTO_SCTP Ta
 101 Return \-1.
 102 The global variable
 103 .Va errno
 104 will be set to
 105 .Er EOPNOTSUPP .
 106 .It Dv PF_INET6 Ta Dv SOCK_DGRAM Ta Dv IPPROTO_UDP Ta
 107 Return 0.
 108 ICMP messages will
 109 .Em not
 110 be generated.
 111 .It Dv PF_INET6 Ta Dv SOCK_STREAM Ta Dv IPPROTO_SCTP Ta
 112 Return 0.
 113 Send queued data and tear down association.
 114 .It Dv PF_INET6 Ta Dv SOCK_STREAM Ta Dv IPPROTO_TCP Ta
 115 Return 0.
 116 Send queued data, wait for ACK, then send FIN.
 117 .El
 118 .\"
 119 .Sh RETURN VALUES
 120 .Rv -std shutdown
 121 .Sh ERRORS
 122 The
 123 .Fn shutdown
 124 system call fails if:
 125 .Bl -tag -width Er
 126 .It Bq Er EBADF
 127 The
 128 .Fa s
 129 argument is not a valid file descriptor.
 130 .It Bq Er EINVAL
 131 The
 132 .Fa how
 133 argument is invalid.
 134 .It Bq Er EOPNOTSUPP
 135 The socket associated with the file descriptor
 136 .Fa s
 137 does not support this operation.
 138 .It Bq Er ENOTCONN
 139 The
 140 .Fa s
 141 argument specifies a
 142 .Dv SOCK_STREAM
 143 socket which is not connected.
 144 .It Bq Er ENOTSOCK
 145 The
 146 .Fa s
 147 argument does not refer to a socket.
 148 .El
 149 .Sh SEE ALSO
 150 .Xr connect 2 ,
 151 .Xr socket 2 ,
 152 .Xr inet 4 ,
 153 .Xr inet6 4
 154 .Sh STANDARDS
 155 The
 156 .Fn shutdown
 157 system call is expected to comply with
 158 .St -p1003.1g-2000 ,
 159 when finalized.
 160 .Sh HISTORY
 161 The
 162 .Fn shutdown
 163 system call appeared in
 164 .Bx 4.2 .
 165 The
 166 .Dv SHUT_RD , SHUT_WR ,
 167 and
 168 .Dv SHUT_RDWR
 169 constants appeared in
 170 .St -p1003.1g-2000 .
 171 .Sh AUTHORS
 172 .An -nosplit
 173 This manual page was updated by
 174 .An Bruce M. Simpson Aq bms@FreeBSD.org
 175 to reflect how
 176 .Fn shutdown
 177 behaves with
 178 .Dv PF_INET
 179 and
 180 .Dv PF_INET6
 181 sockets.
 182 .Sh BUGS
 183 The ICMP
 184 .Dq Li "port unreachable"
 185 message should be generated in response to
 186 datagrams received on a local port to which
 187 .Fa s
 188 is bound
 189 after
 190 .Fn shutdown
 191 is called.