doc.go (7960B)
1 // Copyright 2012 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 // Package ipv4 implements IP-level socket options for the Internet 6 // Protocol version 4. 7 // 8 // The package provides IP-level socket options that allow 9 // manipulation of IPv4 facilities. 10 // 11 // The IPv4 protocol and basic host requirements for IPv4 are defined 12 // in RFC 791 and RFC 1122. 13 // Host extensions for multicasting and socket interface extensions 14 // for multicast source filters are defined in RFC 1112 and RFC 3678. 15 // IGMPv1, IGMPv2 and IGMPv3 are defined in RFC 1112, RFC 2236 and RFC 16 // 3376. 17 // Source-specific multicast is defined in RFC 4607. 18 // 19 // # Unicasting 20 // 21 // The options for unicasting are available for net.TCPConn, 22 // net.UDPConn and net.IPConn which are created as network connections 23 // that use the IPv4 transport. When a single TCP connection carrying 24 // a data flow of multiple packets needs to indicate the flow is 25 // important, Conn is used to set the type-of-service field on the 26 // IPv4 header for each packet. 27 // 28 // ln, err := net.Listen("tcp4", "0.0.0.0:1024") 29 // if err != nil { 30 // // error handling 31 // } 32 // defer ln.Close() 33 // for { 34 // c, err := ln.Accept() 35 // if err != nil { 36 // // error handling 37 // } 38 // go func(c net.Conn) { 39 // defer c.Close() 40 // 41 // The outgoing packets will be labeled DiffServ assured forwarding 42 // class 1 low drop precedence, known as AF11 packets. 43 // 44 // if err := ipv4.NewConn(c).SetTOS(0x28); err != nil { 45 // // error handling 46 // } 47 // if _, err := c.Write(data); err != nil { 48 // // error handling 49 // } 50 // }(c) 51 // } 52 // 53 // # Multicasting 54 // 55 // The options for multicasting are available for net.UDPConn and 56 // net.IPConn which are created as network connections that use the 57 // IPv4 transport. A few network facilities must be prepared before 58 // you begin multicasting, at a minimum joining network interfaces and 59 // multicast groups. 60 // 61 // en0, err := net.InterfaceByName("en0") 62 // if err != nil { 63 // // error handling 64 // } 65 // en1, err := net.InterfaceByIndex(911) 66 // if err != nil { 67 // // error handling 68 // } 69 // group := net.IPv4(224, 0, 0, 250) 70 // 71 // First, an application listens to an appropriate address with an 72 // appropriate service port. 73 // 74 // c, err := net.ListenPacket("udp4", "0.0.0.0:1024") 75 // if err != nil { 76 // // error handling 77 // } 78 // defer c.Close() 79 // 80 // Second, the application joins multicast groups, starts listening to 81 // the groups on the specified network interfaces. Note that the 82 // service port for transport layer protocol does not matter with this 83 // operation as joining groups affects only network and link layer 84 // protocols, such as IPv4 and Ethernet. 85 // 86 // p := ipv4.NewPacketConn(c) 87 // if err := p.JoinGroup(en0, &net.UDPAddr{IP: group}); err != nil { 88 // // error handling 89 // } 90 // if err := p.JoinGroup(en1, &net.UDPAddr{IP: group}); err != nil { 91 // // error handling 92 // } 93 // 94 // The application might set per packet control message transmissions 95 // between the protocol stack within the kernel. When the application 96 // needs a destination address on an incoming packet, 97 // SetControlMessage of PacketConn is used to enable control message 98 // transmissions. 99 // 100 // if err := p.SetControlMessage(ipv4.FlagDst, true); err != nil { 101 // // error handling 102 // } 103 // 104 // The application could identify whether the received packets are 105 // of interest by using the control message that contains the 106 // destination address of the received packet. 107 // 108 // b := make([]byte, 1500) 109 // for { 110 // n, cm, src, err := p.ReadFrom(b) 111 // if err != nil { 112 // // error handling 113 // } 114 // if cm.Dst.IsMulticast() { 115 // if cm.Dst.Equal(group) { 116 // // joined group, do something 117 // } else { 118 // // unknown group, discard 119 // continue 120 // } 121 // } 122 // 123 // The application can also send both unicast and multicast packets. 124 // 125 // p.SetTOS(0x0) 126 // p.SetTTL(16) 127 // if _, err := p.WriteTo(data, nil, src); err != nil { 128 // // error handling 129 // } 130 // dst := &net.UDPAddr{IP: group, Port: 1024} 131 // for _, ifi := range []*net.Interface{en0, en1} { 132 // if err := p.SetMulticastInterface(ifi); err != nil { 133 // // error handling 134 // } 135 // p.SetMulticastTTL(2) 136 // if _, err := p.WriteTo(data, nil, dst); err != nil { 137 // // error handling 138 // } 139 // } 140 // } 141 // 142 // # More multicasting 143 // 144 // An application that uses PacketConn or RawConn may join multiple 145 // multicast groups. For example, a UDP listener with port 1024 might 146 // join two different groups across over two different network 147 // interfaces by using: 148 // 149 // c, err := net.ListenPacket("udp4", "0.0.0.0:1024") 150 // if err != nil { 151 // // error handling 152 // } 153 // defer c.Close() 154 // p := ipv4.NewPacketConn(c) 155 // if err := p.JoinGroup(en0, &net.UDPAddr{IP: net.IPv4(224, 0, 0, 248)}); err != nil { 156 // // error handling 157 // } 158 // if err := p.JoinGroup(en0, &net.UDPAddr{IP: net.IPv4(224, 0, 0, 249)}); err != nil { 159 // // error handling 160 // } 161 // if err := p.JoinGroup(en1, &net.UDPAddr{IP: net.IPv4(224, 0, 0, 249)}); err != nil { 162 // // error handling 163 // } 164 // 165 // It is possible for multiple UDP listeners that listen on the same 166 // UDP port to join the same multicast group. The net package will 167 // provide a socket that listens to a wildcard address with reusable 168 // UDP port when an appropriate multicast address prefix is passed to 169 // the net.ListenPacket or net.ListenUDP. 170 // 171 // c1, err := net.ListenPacket("udp4", "224.0.0.0:1024") 172 // if err != nil { 173 // // error handling 174 // } 175 // defer c1.Close() 176 // c2, err := net.ListenPacket("udp4", "224.0.0.0:1024") 177 // if err != nil { 178 // // error handling 179 // } 180 // defer c2.Close() 181 // p1 := ipv4.NewPacketConn(c1) 182 // if err := p1.JoinGroup(en0, &net.UDPAddr{IP: net.IPv4(224, 0, 0, 248)}); err != nil { 183 // // error handling 184 // } 185 // p2 := ipv4.NewPacketConn(c2) 186 // if err := p2.JoinGroup(en0, &net.UDPAddr{IP: net.IPv4(224, 0, 0, 248)}); err != nil { 187 // // error handling 188 // } 189 // 190 // Also it is possible for the application to leave or rejoin a 191 // multicast group on the network interface. 192 // 193 // if err := p.LeaveGroup(en0, &net.UDPAddr{IP: net.IPv4(224, 0, 0, 248)}); err != nil { 194 // // error handling 195 // } 196 // if err := p.JoinGroup(en0, &net.UDPAddr{IP: net.IPv4(224, 0, 0, 250)}); err != nil { 197 // // error handling 198 // } 199 // 200 // # Source-specific multicasting 201 // 202 // An application that uses PacketConn or RawConn on IGMPv3 supported 203 // platform is able to join source-specific multicast groups. 204 // The application may use JoinSourceSpecificGroup and 205 // LeaveSourceSpecificGroup for the operation known as "include" mode, 206 // 207 // ssmgroup := net.UDPAddr{IP: net.IPv4(232, 7, 8, 9)} 208 // ssmsource := net.UDPAddr{IP: net.IPv4(192, 168, 0, 1)} 209 // if err := p.JoinSourceSpecificGroup(en0, &ssmgroup, &ssmsource); err != nil { 210 // // error handling 211 // } 212 // if err := p.LeaveSourceSpecificGroup(en0, &ssmgroup, &ssmsource); err != nil { 213 // // error handling 214 // } 215 // 216 // or JoinGroup, ExcludeSourceSpecificGroup, 217 // IncludeSourceSpecificGroup and LeaveGroup for the operation known 218 // as "exclude" mode. 219 // 220 // exclsource := net.UDPAddr{IP: net.IPv4(192, 168, 0, 254)} 221 // if err := p.JoinGroup(en0, &ssmgroup); err != nil { 222 // // error handling 223 // } 224 // if err := p.ExcludeSourceSpecificGroup(en0, &ssmgroup, &exclsource); err != nil { 225 // // error handling 226 // } 227 // if err := p.LeaveGroup(en0, &ssmgroup); err != nil { 228 // // error handling 229 // } 230 // 231 // Note that it depends on each platform implementation what happens 232 // when an application which runs on IGMPv3 unsupported platform uses 233 // JoinSourceSpecificGroup and LeaveSourceSpecificGroup. 234 // In general the platform tries to fall back to conversations using 235 // IGMPv1 or IGMPv2 and starts to listen to multicast traffic. 236 // In the fallback case, ExcludeSourceSpecificGroup and 237 // IncludeSourceSpecificGroup may return an error. 238 package ipv4 // import "golang.org/x/net/ipv4" 239 240 // BUG(mikio): This package is not implemented on JS, NaCl and Plan 9.