cpan/Socket/Socket.pm

   1 package Socket;
   2
   3 use strict;
   4 { use 5.006001; }
   5
   6 our $VERSION = '2.024';
   7
   8 =head1 NAME
   9
  10 C<Socket> - networking constants and support functions
  11
  12 =head1 SYNOPSIS
  13
  14 C<Socket> a low-level module used by, among other things, the L<IO::Socket>
  15 family of modules. The following examples demonstrate some low-level uses but
  16 a practical program would likely use the higher-level API provided by
  17 C<IO::Socket> or similar instead.
  18
  19  use Socket qw(PF_INET SOCK_STREAM pack_sockaddr_in inet_aton);
  20
  21  socket(my $socket, PF_INET, SOCK_STREAM, 0)
  22      or die "socket: $!";
  23
  24  my $port = getservbyname "echo", "tcp";
  25  connect($socket, pack_sockaddr_in($port, inet_aton("localhost")))
  26      or die "connect: $!";
  27
  28  print $socket "Hello, world!\n";
  29  print <$socket>;
  30
  31 See also the L</EXAMPLES> section.
  32
  33 =head1 DESCRIPTION
  34
  35 This module provides a variety of constants, structure manipulators and other
  36 functions related to socket-based networking. The values and functions
  37 provided are useful when used in conjunction with Perl core functions such as
  38 socket(), setsockopt() and bind(). It also provides several other support
  39 functions, mostly for dealing with conversions of network addresses between
  40 human-readable and native binary forms, and for hostname resolver operations.
  41
  42 Some constants and functions are exported by default by this module; but for
  43 backward-compatibility any recently-added symbols are not exported by default
  44 and must be requested explicitly. When an import list is provided to the
  45 C<use Socket> line, the default exports are not automatically imported. It is
  46 therefore best practice to always to explicitly list all the symbols required.
  47
  48 Also, some common socket "newline" constants are provided: the constants
  49 C<CR>, C<LF>, and C<CRLF>, as well as C<$CR>, C<$LF>, and C<$CRLF>, which map
  50 to C<\015>, C<\012>, and C<\015\012>. If you do not want to use the literal
  51 characters in your programs, then use the constants provided here. They are
  52 not exported by default, but can be imported individually, and with the
  53 C<:crlf> export tag:
  54
  55  use Socket qw(:DEFAULT :crlf);
  56
  57  $sock->print("GET / HTTP/1.0$CRLF");
  58
  59 The entire getaddrinfo() subsystem can be exported using the tag C<:addrinfo>;
  60 this exports the getaddrinfo() and getnameinfo() functions, and all the
  61 C<AI_*>, C<NI_*>, C<NIx_*> and C<EAI_*> constants.
  62
  63 =cut
  64
  65 =head1 CONSTANTS
  66
  67 In each of the following groups, there may be many more constants provided
  68 than just the ones given as examples in the section heading. If the heading
  69 ends C<...> then this means there are likely more; the exact constants
  70 provided will depend on the OS and headers found at compile-time.
  71
  72 =cut
  73
  74 =head2 PF_INET, PF_INET6, PF_UNIX, ...
  75
  76 Protocol family constants to use as the first argument to socket() or the
  77 value of the C<SO_DOMAIN> or C<SO_FAMILY> socket option.
  78
  79 =head2 AF_INET, AF_INET6, AF_UNIX, ...
  80
  81 Address family constants used by the socket address structures, to pass to
  82 such functions as inet_pton() or getaddrinfo(), or are returned by such
  83 functions as sockaddr_family().
  84
  85 =head2 SOCK_STREAM, SOCK_DGRAM, SOCK_RAW, ...
  86
  87 Socket type constants to use as the second argument to socket(), or the value
  88 of the C<SO_TYPE> socket option.
  89
  90 =head2 SOCK_NONBLOCK. SOCK_CLOEXEC
  91
  92 Linux-specific shortcuts to specify the C<O_NONBLOCK> and C<FD_CLOEXEC> flags
  93 during a C<socket(2)> call.
  94
  95  socket( my $sockh, PF_INET, SOCK_DGRAM|SOCK_NONBLOCK, 0 )
  96
  97 =head2 SOL_SOCKET
  98
  99 Socket option level constant for setsockopt() and getsockopt().
 100
 101 =head2 SO_ACCEPTCONN, SO_BROADCAST, SO_ERROR, ...
 102
 103 Socket option name constants for setsockopt() and getsockopt() at the
 104 C<SOL_SOCKET> level.
 105
 106 =head2 IP_OPTIONS, IP_TOS, IP_TTL, ...
 107
 108 Socket option name constants for IPv4 socket options at the C<IPPROTO_IP>
 109 level.
 110
 111 =head2 IP_PMTUDISC_WANT, IP_PMTUDISC_DONT, ...
 112
 113 Socket option value contants for C<IP_MTU_DISCOVER> socket option.
 114
 115 =head2 IPTOS_LOWDELAY, IPTOS_THROUGHPUT, IPTOS_RELIABILITY, ...
 116
 117 Socket option value constants for C<IP_TOS> socket option.
 118
 119 =head2 MSG_BCAST, MSG_OOB, MSG_TRUNC, ...
 120
 121 Message flag constants for send() and recv().
 122
 123 =head2 SHUT_RD, SHUT_RDWR, SHUT_WR
 124
 125 Direction constants for shutdown().
 126
 127 =head2 INADDR_ANY, INADDR_BROADCAST, INADDR_LOOPBACK, INADDR_NONE
 128
 129 Constants giving the special C<AF_INET> addresses for wildcard, broadcast,
 130 local loopback, and invalid addresses.
 131
 132 Normally equivalent to inet_aton('0.0.0.0'), inet_aton('255.255.255.255'),
 133 inet_aton('localhost') and inet_aton('255.255.255.255') respectively.
 134
 135 =head2 IPPROTO_IP, IPPROTO_IPV6, IPPROTO_TCP, ...
 136
 137 IP protocol constants to use as the third argument to socket(), the level
 138 argument to getsockopt() or setsockopt(), or the value of the C<SO_PROTOCOL>
 139 socket option.
 140
 141 =head2 TCP_CORK, TCP_KEEPALIVE, TCP_NODELAY, ...
 142
 143 Socket option name constants for TCP socket options at the C<IPPROTO_TCP>
 144 level.
 145
 146 =head2 IN6ADDR_ANY, IN6ADDR_LOOPBACK
 147
 148 Constants giving the special C<AF_INET6> addresses for wildcard and local
 149 loopback.
 150
 151 Normally equivalent to inet_pton(AF_INET6, "::") and
 152 inet_pton(AF_INET6, "::1") respectively.
 153
 154 =head2 IPV6_ADD_MEMBERSHIP, IPV6_MTU, IPV6_V6ONLY, ...
 155
 156 Socket option name constants for IPv6 socket options at the C<IPPROTO_IPV6>
 157 level.
 158
 159 =cut
 160
 161 # Still undocumented: SCM_*, SOMAXCONN, IOV_MAX, UIO_MAXIOV
 162
 163 =head1 STRUCTURE MANIPULATORS
 164
 165 The following functions convert between lists of Perl values and packed binary
 166 strings representing structures.
 167
 168 =cut
 169
 170 =head2 $family = sockaddr_family $sockaddr
 171
 172 Takes a packed socket address (as returned by pack_sockaddr_in(),
 173 pack_sockaddr_un() or the perl builtin functions getsockname() and
 174 getpeername()). Returns the address family tag. This will be one of the
 175 C<AF_*> constants, such as C<AF_INET> for a C<sockaddr_in> addresses or
 176 C<AF_UNIX> for a C<sockaddr_un>. It can be used to figure out what unpack to
 177 use for a sockaddr of unknown type.
 178
 179 =head2 $sockaddr = pack_sockaddr_in $port, $ip_address
 180
 181 Takes two arguments, a port number and an opaque string (as returned by
 182 inet_aton(), or a v-string). Returns the C<sockaddr_in> structure with those
 183 arguments packed in and C<AF_INET> filled in. For Internet domain sockets,
 184 this structure is normally what you need for the arguments in bind(),
 185 connect(), and send().
 186
 187 An undefined $port argument is taken as zero; an undefined $ip_address is
 188 considered a fatal error.
 189
 190 =head2 ($port, $ip_address) = unpack_sockaddr_in $sockaddr
 191
 192 Takes a C<sockaddr_in> structure (as returned by pack_sockaddr_in(),
 193 getpeername() or recv()). Returns a list of two elements: the port and an
 194 opaque string representing the IP address (you can use inet_ntoa() to convert
 195 the address to the four-dotted numeric format). Will croak if the structure
 196 does not represent an C<AF_INET> address.
 197
 198 In scalar context will return just the IP address.
 199
 200 =head2 $sockaddr = sockaddr_in $port, $ip_address
 201
 202 =head2 ($port, $ip_address) = sockaddr_in $sockaddr
 203
 204 A wrapper of pack_sockaddr_in() or unpack_sockaddr_in(). In list context,
 205 unpacks its argument and returns a list consisting of the port and IP address.
 206 In scalar context, packs its port and IP address arguments as a C<sockaddr_in>
 207 and returns it.
 208
 209 Provided largely for legacy compatibility; it is better to use
 210 pack_sockaddr_in() or unpack_sockaddr_in() explicitly.
 211
 212 =head2 $sockaddr = pack_sockaddr_in6 $port, $ip6_address, [$scope_id, [$flowinfo]]
 213
 214 Takes two to four arguments, a port number, an opaque string (as returned by
 215 inet_pton()), optionally a scope ID number, and optionally a flow label
 216 number. Returns the C<sockaddr_in6> structure with those arguments packed in
 217 and C<AF_INET6> filled in. IPv6 equivalent of pack_sockaddr_in().
 218
 219 An undefined $port argument is taken as zero; an undefined $ip6_address is
 220 considered a fatal error.
 221
 222 =head2 ($port, $ip6_address, $scope_id, $flowinfo) = unpack_sockaddr_in6 $sockaddr
 223
 224 Takes a C<sockaddr_in6> structure. Returns a list of four elements: the port
 225 number, an opaque string representing the IPv6 address, the scope ID, and the
 226 flow label. (You can use inet_ntop() to convert the address to the usual
 227 string format). Will croak if the structure does not represent an C<AF_INET6>
 228 address.
 229
 230 In scalar context will return just the IP address.
 231
 232 =head2 $sockaddr = sockaddr_in6 $port, $ip6_address, [$scope_id, [$flowinfo]]
 233
 234 =head2 ($port, $ip6_address, $scope_id, $flowinfo) = sockaddr_in6 $sockaddr
 235
 236 A wrapper of pack_sockaddr_in6() or unpack_sockaddr_in6(). In list context,
 237 unpacks its argument according to unpack_sockaddr_in6(). In scalar context,
 238 packs its arguments according to pack_sockaddr_in6().
 239
 240 Provided largely for legacy compatibility; it is better to use
 241 pack_sockaddr_in6() or unpack_sockaddr_in6() explicitly.
 242
 243 =head2 $sockaddr = pack_sockaddr_un $path
 244
 245 Takes one argument, a pathname. Returns the C<sockaddr_un> structure with that
 246 path packed in with C<AF_UNIX> filled in. For C<PF_UNIX> sockets, this
 247 structure is normally what you need for the arguments in bind(), connect(),
 248 and send().
 249
 250 =head2 ($path) = unpack_sockaddr_un $sockaddr
 251
 252 Takes a C<sockaddr_un> structure (as returned by pack_sockaddr_un(),
 253 getpeername() or recv()). Returns a list of one element: the pathname. Will
 254 croak if the structure does not represent an C<AF_UNIX> address.
 255
 256 =head2 $sockaddr = sockaddr_un $path
 257
 258 =head2 ($path) = sockaddr_un $sockaddr
 259
 260 A wrapper of pack_sockaddr_un() or unpack_sockaddr_un(). In a list context,
 261 unpacks its argument and returns a list consisting of the pathname. In a
 262 scalar context, packs its pathname as a C<sockaddr_un> and returns it.
 263
 264 Provided largely for legacy compatibility; it is better to use
 265 pack_sockaddr_un() or unpack_sockaddr_un() explicitly.
 266
 267 These are only supported if your system has E<lt>F<sys/un.h>E<gt>.
 268
 269 =head2 $ip_mreq = pack_ip_mreq $multiaddr, $interface
 270
 271 Takes an IPv4 multicast address and optionally an interface address (or
 272 C<INADDR_ANY>). Returns the C<ip_mreq> structure with those arguments packed
 273 in. Suitable for use with the C<IP_ADD_MEMBERSHIP> and C<IP_DROP_MEMBERSHIP>
 274 sockopts.
 275
 276 =head2 ($multiaddr, $interface) = unpack_ip_mreq $ip_mreq
 277
 278 Takes an C<ip_mreq> structure. Returns a list of two elements; the IPv4
 279 multicast address and interface address.
 280
 281 =head2 $ip_mreq_source = pack_ip_mreq_source $multiaddr, $source, $interface
 282
 283 Takes an IPv4 multicast address, source address, and optionally an interface
 284 address (or C<INADDR_ANY>). Returns the C<ip_mreq_source> structure with those
 285 arguments packed in. Suitable for use with the C<IP_ADD_SOURCE_MEMBERSHIP>
 286 and C<IP_DROP_SOURCE_MEMBERSHIP> sockopts.
 287
 288 =head2 ($multiaddr, $source, $interface) = unpack_ip_mreq_source $ip_mreq
 289
 290 Takes an C<ip_mreq_source> structure. Returns a list of three elements; the
 291 IPv4 multicast address, source address and interface address.
 292
 293 =head2 $ipv6_mreq = pack_ipv6_mreq $multiaddr6, $ifindex
 294
 295 Takes an IPv6 multicast address and an interface number. Returns the
 296 C<ipv6_mreq> structure with those arguments packed in. Suitable for use with
 297 the C<IPV6_ADD_MEMBERSHIP> and C<IPV6_DROP_MEMBERSHIP> sockopts.
 298
 299 =head2 ($multiaddr6, $ifindex) = unpack_ipv6_mreq $ipv6_mreq
 300
 301 Takes an C<ipv6_mreq> structure. Returns a list of two elements; the IPv6
 302 address and an interface number.
 303
 304 =cut
 305
 306 =head1 FUNCTIONS
 307
 308 =cut
 309
 310 =head2 $ip_address = inet_aton $string
 311
 312 Takes a string giving the name of a host, or a textual representation of an IP
 313 address and translates that to an packed binary address structure suitable to
 314 pass to pack_sockaddr_in(). If passed a hostname that cannot be resolved,
 315 returns C<undef>. For multi-homed hosts (hosts with more than one address),
 316 the first address found is returned.
 317
 318 For portability do not assume that the result of inet_aton() is 32 bits wide,
 319 in other words, that it would contain only the IPv4 address in network order.
 320
 321 This IPv4-only function is provided largely for legacy reasons. Newly-written
 322 code should use getaddrinfo() or inet_pton() instead for IPv6 support.
 323
 324 =head2 $string = inet_ntoa $ip_address
 325
 326 Takes a packed binary address structure such as returned by
 327 unpack_sockaddr_in() (or a v-string representing the four octets of the IPv4
 328 address in network order) and translates it into a string of the form
 329 C<d.d.d.d> where the C<d>s are numbers less than 256 (the normal
 330 human-readable four dotted number notation for Internet addresses).
 331
 332 This IPv4-only function is provided largely for legacy reasons. Newly-written
 333 code should use getnameinfo() or inet_ntop() instead for IPv6 support.
 334
 335 =head2 $address = inet_pton $family, $string
 336
 337 Takes an address family (such as C<AF_INET> or C<AF_INET6>) and a string
 338 containing a textual representation of an address in that family and
 339 translates that to an packed binary address structure.
 340
 341 See also getaddrinfo() for a more powerful and flexible function to look up
 342 socket addresses given hostnames or textual addresses.
 343
 344 =head2 $string = inet_ntop $family, $address
 345
 346 Takes an address family and a packed binary address structure and translates
 347 it into a human-readable textual representation of the address; typically in
 348 C<d.d.d.d> form for C<AF_INET> or C<hhhh:hhhh::hhhh> form for C<AF_INET6>.
 349
 350 See also getnameinfo() for a more powerful and flexible function to turn
 351 socket addresses into human-readable textual representations.
 352
 353 =head2 ($err, @result) = getaddrinfo $host, $service, [$hints]
 354
 355 Given both a hostname and service name, this function attempts to resolve the
 356 host name into a list of network addresses, and the service name into a
 357 protocol and port number, and then returns a list of address structures
 358 suitable to connect() to it.
 359
 360 Given just a host name, this function attempts to resolve it to a list of
 361 network addresses, and then returns a list of address structures giving these
 362 addresses.
 363
 364 Given just a service name, this function attempts to resolve it to a protocol
 365 and port number, and then returns a list of address structures that represent
 366 it suitable to bind() to. This use should be combined with the C<AI_PASSIVE>
 367 flag; see below.
 368
 369 Given neither name, it generates an error.
 370
 371 If present, $hints should be a reference to a hash, where the following keys
 372 are recognised:
 373
 374 =over 4
 375
 376 =item flags => INT
 377
 378 A bitfield containing C<AI_*> constants; see below.
 379
 380 =item family => INT
 381
 382 Restrict to only generating addresses in this address family
 383
 384 =item socktype => INT
 385
 386 Restrict to only generating addresses of this socket type
 387
 388 =item protocol => INT
 389
 390 Restrict to only generating addresses for this protocol
 391
 392 =back
 393
 394 The return value will be a list; the first value being an error indication,
 395 followed by a list of address structures (if no error occurred).
 396
 397 The error value will be a dualvar; comparable to the C<EAI_*> error constants,
 398 or printable as a human-readable error message string. If no error occurred it
 399 will be zero numerically and an empty string.
 400
 401 Each value in the results list will be a hash reference containing the following
 402 fields:
 403
 404 =over 4
 405
 406 =item family => INT
 407
 408 The address family (e.g. C<AF_INET>)
 409
 410 =item socktype => INT
 411
 412 The socket type (e.g. C<SOCK_STREAM>)
 413
 414 =item protocol => INT
 415
 416 The protocol (e.g. C<IPPROTO_TCP>)
 417
 418 =item addr => STRING
 419
 420 The address in a packed string (such as would be returned by
 421 pack_sockaddr_in())
 422
 423 =item canonname => STRING
 424
 425 The canonical name for the host if the C<AI_CANONNAME> flag was provided, or
 426 C<undef> otherwise. This field will only be present on the first returned
 427 address.
 428
 429 =back
 430
 431 The following flag constants are recognised in the $hints hash. Other flag
 432 constants may exist as provided by the OS.
 433
 434 =over 4
 435
 436 =item AI_PASSIVE
 437
 438 Indicates that this resolution is for a local bind() for a passive (i.e.
 439 listening) socket, rather than an active (i.e. connecting) socket.
 440
 441 =item AI_CANONNAME
 442
 443 Indicates that the caller wishes the canonical hostname (C<canonname>) field
 444 of the result to be filled in.
 445
 446 =item AI_NUMERICHOST
 447
 448 Indicates that the caller will pass a numeric address, rather than a hostname,
 449 and that getaddrinfo() must not perform a resolve operation on this name. This
 450 flag will prevent a possibly-slow network lookup operation, and instead return
 451 an error if a hostname is passed.
 452
 453 =back
 454
 455 =head2 ($err, $hostname, $servicename) = getnameinfo $sockaddr, [$flags, [$xflags]]
 456
 457 Given a packed socket address (such as from getsockname(), getpeername(), or
 458 returned by getaddrinfo() in a C<addr> field), returns the hostname and
 459 symbolic service name it represents. $flags may be a bitmask of C<NI_*>
 460 constants, or defaults to 0 if unspecified.
 461
 462 The return value will be a list; the first value being an error condition,
 463 followed by the hostname and service name.
 464
 465 The error value will be a dualvar; comparable to the C<EAI_*> error constants,
 466 or printable as a human-readable error message string. The host and service
 467 names will be plain strings.
 468
 469 The following flag constants are recognised as $flags. Other flag constants may
 470 exist as provided by the OS.
 471
 472 =over 4
 473
 474 =item NI_NUMERICHOST
 475
 476 Requests that a human-readable string representation of the numeric address be
 477 returned directly, rather than performing a name resolve operation that may
 478 convert it into a hostname. This will also avoid potentially-blocking network
 479 IO.
 480
 481 =item NI_NUMERICSERV
 482
 483 Requests that the port number be returned directly as a number representation
 484 rather than performing a name resolve operation that may convert it into a
 485 service name.
 486
 487 =item NI_NAMEREQD
 488
 489 If a name resolve operation fails to provide a name, then this flag will cause
 490 getnameinfo() to indicate an error, rather than returning the numeric
 491 representation as a human-readable string.
 492
 493 =item NI_DGRAM
 494
 495 Indicates that the socket address relates to a C<SOCK_DGRAM> socket, for the
 496 services whose name differs between TCP and UDP protocols.
 497
 498 =back
 499
 500 The following constants may be supplied as $xflags.
 501
 502 =over 4
 503
 504 =item NIx_NOHOST
 505
 506 Indicates that the caller is not interested in the hostname of the result, so
 507 it does not have to be converted. C<undef> will be returned as the hostname.
 508
 509 =item NIx_NOSERV
 510
 511 Indicates that the caller is not interested in the service name of the result,
 512 so it does not have to be converted. C<undef> will be returned as the service
 513 name.
 514
 515 =back
 516
 517 =head1 getaddrinfo() / getnameinfo() ERROR CONSTANTS
 518
 519 The following constants may be returned by getaddrinfo() or getnameinfo().
 520 Others may be provided by the OS.
 521
 522 =over 4
 523
 524 =item EAI_AGAIN
 525
 526 A temporary failure occurred during name resolution. The operation may be
 527 successful if it is retried later.
 528
 529 =item EAI_BADFLAGS
 530
 531 The value of the C<flags> hint to getaddrinfo(), or the $flags parameter to
 532 getnameinfo() contains unrecognised flags.
 533
 534 =item EAI_FAMILY
 535
 536 The C<family> hint to getaddrinfo(), or the family of the socket address
 537 passed to getnameinfo() is not supported.
 538
 539 =item EAI_NODATA
 540
 541 The host name supplied to getaddrinfo() did not provide any usable address
 542 data.
 543
 544 =item EAI_NONAME
 545
 546 The host name supplied to getaddrinfo() does not exist, or the address
 547 supplied to getnameinfo() is not associated with a host name and the
 548 C<NI_NAMEREQD> flag was supplied.
 549
 550 =item EAI_SERVICE
 551
 552 The service name supplied to getaddrinfo() is not available for the socket
 553 type given in the $hints.
 554
 555 =back
 556
 557 =cut
 558
 559 =head1 EXAMPLES
 560
 561 =head2 Lookup for connect()
 562
 563 The getaddrinfo() function converts a hostname and a service name into a list
 564 of structures, each containing a potential way to connect() to the named
 565 service on the named host.
 566
 567  use IO::Socket;
 568  use Socket qw(SOCK_STREAM getaddrinfo);
 569
 570  my %hints = (socktype => SOCK_STREAM);
 571  my ($err, @res) = getaddrinfo("localhost", "echo", \%hints);
 572  die "Cannot getaddrinfo - $err" if $err;
 573
 574  my $sock;
 575
 576  foreach my $ai (@res) {
 577      my $candidate = IO::Socket->new();
 578
 579      $candidate->socket($ai->{family}, $ai->{socktype}, $ai->{protocol})
 580          or next;
 581
 582      $candidate->connect($ai->{addr})
 583          or next;
 584
 585      $sock = $candidate;
 586      last;
 587  }
 588
 589  die "Cannot connect to localhost:echo" unless $sock;
 590
 591  $sock->print("Hello, world!\n");
 592  print <$sock>;
 593
 594 Because a list of potential candidates is returned, the C<while> loop tries
 595 each in turn until it finds one that succeeds both the socket() and connect()
 596 calls.
 597
 598 This function performs the work of the legacy functions gethostbyname(),
 599 getservbyname(), inet_aton() and pack_sockaddr_in().
 600
 601 In practice this logic is better performed by L<IO::Socket::IP>.
 602
 603 =head2 Making a human-readable string out of an address
 604
 605 The getnameinfo() function converts a socket address, such as returned by
 606 getsockname() or getpeername(), into a pair of human-readable strings
 607 representing the address and service name.
 608
 609  use IO::Socket::IP;
 610  use Socket qw(getnameinfo);
 611
 612  my $server = IO::Socket::IP->new(LocalPort => 12345, Listen => 1) or
 613      die "Cannot listen - $@";
 614
 615  my $socket = $server->accept or die "accept: $!";
 616
 617  my ($err, $hostname, $servicename) = getnameinfo($socket->peername);
 618  die "Cannot getnameinfo - $err" if $err;
 619
 620  print "The peer is connected from $hostname\n";
 621
 622 Since in this example only the hostname was used, the redundant conversion of
 623 the port number into a service name may be omitted by passing the
 624 C<NIx_NOSERV> flag.
 625
 626  use Socket qw(getnameinfo NIx_NOSERV);
 627
 628  my ($err, $hostname) = getnameinfo($socket->peername, 0, NIx_NOSERV);
 629
 630 This function performs the work of the legacy functions unpack_sockaddr_in(),
 631 inet_ntoa(), gethostbyaddr() and getservbyport().
 632
 633 In practice this logic is better performed by L<IO::Socket::IP>.
 634
 635 =head2 Resolving hostnames into IP addresses
 636
 637 To turn a hostname into a human-readable plain IP address use getaddrinfo()
 638 to turn the hostname into a list of socket structures, then getnameinfo() on
 639 each one to make it a readable IP address again.
 640
 641  use Socket qw(:addrinfo SOCK_RAW);
 642
 643  my ($err, @res) = getaddrinfo($hostname, "", {socktype => SOCK_RAW});
 644  die "Cannot getaddrinfo - $err" if $err;
 645
 646  while( my $ai = shift @res ) {
 647      my ($err, $ipaddr) = getnameinfo($ai->{addr}, NI_NUMERICHOST, NIx_NOSERV);
 648      die "Cannot getnameinfo - $err" if $err;
 649
 650      print "$ipaddr\n";
 651  }
 652
 653 The C<socktype> hint to getaddrinfo() filters the results to only include one
 654 socket type and protocol. Without this most OSes return three combinations,
 655 for C<SOCK_STREAM>, C<SOCK_DGRAM> and C<SOCK_RAW>, resulting in triplicate
 656 output of addresses. The C<NI_NUMERICHOST> flag to getnameinfo() causes it to
 657 return a string-formatted plain IP address, rather than reverse resolving it
 658 back into a hostname.
 659
 660 This combination performs the work of the legacy functions gethostbyname()
 661 and inet_ntoa().
 662
 663 =head2 Accessing socket options
 664
 665 The many C<SO_*> and other constants provide the socket option names for
 666 getsockopt() and setsockopt().
 667
 668  use IO::Socket::INET;
 669  use Socket qw(SOL_SOCKET SO_RCVBUF IPPROTO_IP IP_TTL);
 670
 671  my $socket = IO::Socket::INET->new(LocalPort => 0, Proto => 'udp')
 672      or die "Cannot create socket: $@";
 673
 674  $socket->setsockopt(SOL_SOCKET, SO_RCVBUF, 64*1024) or
 675      die "setsockopt: $!";
 676
 677  print "Receive buffer is ", $socket->getsockopt(SOL_SOCKET, SO_RCVBUF),
 678      " bytes\n";
 679
 680  print "IP TTL is ", $socket->getsockopt(IPPROTO_IP, IP_TTL), "\n";
 681
 682 As a convenience, L<IO::Socket>'s setsockopt() method will convert a number
 683 into a packed byte buffer, and getsockopt() will unpack a byte buffer of the
 684 correct size back into a number.
 685
 686 =cut
 687
 688 =head1 AUTHOR
 689
 690 This module was originally maintained in Perl core by the Perl 5 Porters.
 691
 692 It was extracted to dual-life on CPAN at version 1.95 by
 693 Paul Evans <leonerd@leonerd.org.uk>
 694
 695 =cut
 696
 697 use Carp;
 698 use warnings::register;
 699
 700 require Exporter;
 701 require XSLoader;
 702 our @ISA = qw(Exporter);
 703
 704 # <@Nicholas> you can't change @EXPORT without breaking the implicit API
 705 # Please put any new constants in @EXPORT_OK!
 706
 707 # List re-ordered to match documentation above. Try to keep the ordering
 708 # consistent so it's easier to see which ones are or aren't documented.
 709 our @EXPORT = qw(
 710         PF_802 PF_AAL PF_APPLETALK PF_CCITT PF_CHAOS PF_CTF PF_DATAKIT
 711         PF_DECnet PF_DLI PF_ECMA PF_GOSIP PF_HYLINK PF_IMPLINK PF_INET PF_INET6
 712         PF_ISO PF_KEY PF_LAST PF_LAT PF_LINK PF_MAX PF_NBS PF_NIT PF_NS PF_OSI
 713         PF_OSINET PF_PUP PF_ROUTE PF_SNA PF_UNIX PF_UNSPEC PF_USER PF_WAN
 714         PF_X25
 715
 716         AF_802 AF_AAL AF_APPLETALK AF_CCITT AF_CHAOS AF_CTF AF_DATAKIT
 717         AF_DECnet AF_DLI AF_ECMA AF_GOSIP AF_HYLINK AF_IMPLINK AF_INET AF_INET6
 718         AF_ISO AF_KEY AF_LAST AF_LAT AF_LINK AF_MAX AF_NBS AF_NIT AF_NS AF_OSI
 719         AF_OSINET AF_PUP AF_ROUTE AF_SNA AF_UNIX AF_UNSPEC AF_USER AF_WAN
 720         AF_X25
 721
 722         SOCK_DGRAM SOCK_RAW SOCK_RDM SOCK_SEQPACKET SOCK_STREAM
 723
 724         SOL_SOCKET
 725
 726         SO_ACCEPTCONN SO_ATTACH_FILTER SO_BACKLOG SO_BROADCAST SO_CHAMELEON
 727         SO_DEBUG SO_DETACH_FILTER SO_DGRAM_ERRIND SO_DOMAIN SO_DONTLINGER
 728         SO_DONTROUTE SO_ERROR SO_FAMILY SO_KEEPALIVE SO_LINGER SO_OOBINLINE
 729         SO_PASSCRED SO_PASSIFNAME SO_PEERCRED SO_PROTOCOL SO_PROTOTYPE
 730         SO_RCVBUF SO_RCVLOWAT SO_RCVTIMEO SO_REUSEADDR SO_REUSEPORT
 731         SO_SECURITY_AUTHENTICATION SO_SECURITY_ENCRYPTION_NETWORK
 732         SO_SECURITY_ENCRYPTION_TRANSPORT SO_SNDBUF SO_SNDLOWAT SO_SNDTIMEO
 733         SO_STATE SO_TYPE SO_USELOOPBACK SO_XOPEN SO_XSE
 734
 735         IP_HDRINCL IP_OPTIONS IP_RECVOPTS IP_RECVRETOPTS IP_RETOPTS IP_TOS
 736         IP_TTL
 737
 738         MSG_BCAST MSG_BTAG MSG_CTLFLAGS MSG_CTLIGNORE MSG_CTRUNC MSG_DONTROUTE
 739         MSG_DONTWAIT MSG_EOF MSG_EOR MSG_ERRQUEUE MSG_ETAG MSG_FASTOPEN MSG_FIN
 740         MSG_MAXIOVLEN MSG_MCAST MSG_NOSIGNAL MSG_OOB MSG_PEEK MSG_PROXY MSG_RST
 741         MSG_SYN MSG_TRUNC MSG_URG MSG_WAITALL MSG_WIRE
 742
 743         SHUT_RD SHUT_RDWR SHUT_WR
 744
 745         INADDR_ANY INADDR_BROADCAST INADDR_LOOPBACK INADDR_NONE
 746
 747         SCM_CONNECT SCM_CREDENTIALS SCM_CREDS SCM_RIGHTS SCM_TIMESTAMP
 748
 749         SOMAXCONN
 750
 751         IOV_MAX
 752         UIO_MAXIOV
 753
 754         sockaddr_family
 755         pack_sockaddr_in  unpack_sockaddr_in  sockaddr_in
 756         pack_sockaddr_in6 unpack_sockaddr_in6 sockaddr_in6
 757         pack_sockaddr_un  unpack_sockaddr_un  sockaddr_un
 758
 759         inet_aton inet_ntoa
 760 );
 761
 762 # List re-ordered to match documentation above. Try to keep the ordering
 763 # consistent so it's easier to see which ones are or aren't documented.
 764 our @EXPORT_OK = qw(
 765         CR LF CRLF $CR $LF $CRLF
 766
 767         SOCK_NONBLOCK SOCK_CLOEXEC
 768
 769         IP_ADD_MEMBERSHIP IP_ADD_SOURCE_MEMBERSHIP IP_BIND_ADDRESS_NO_PORT
 770         IP_DROP_MEMBERSHIP IP_DROP_SOURCE_MEMBERSHIP IP_FREEBIND
 771         IP_MULTICAST_ALL IP_MULTICAST_IF IP_MULTICAST_LOOP IP_MULTICAST_TTL
 772         IP_MTU IP_MTU_DISCOVER IP_NODEFRAG IP_RECVERR IP_TRANSPARENT
 773
 774         IPPROTO_IP IPPROTO_IPV6 IPPROTO_RAW IPPROTO_ICMP IPPROTO_IGMP
 775         IPPROTO_TCP IPPROTO_UDP IPPROTO_GRE IPPROTO_ESP IPPROTO_AH
 776         IPPROTO_SCTP
 777
 778         IP_PMTUDISC_DO IP_PMTUDISC_DONT IP_PMTUDISC_PROBE IP_PMTUDISC_WANT
 779
 780         IPTOS_LOWDELAY IPTOS_THROUGHPUT IPTOS_RELIABILITY IPTOS_MINCOST
 781
 782         TCP_CONGESTION TCP_CONNECTIONTIMEOUT TCP_CORK TCP_DEFER_ACCEPT
 783         TCP_FASTOPEN TCP_INFO TCP_INIT_CWND TCP_KEEPALIVE TCP_KEEPCNT
 784         TCP_KEEPIDLE TCP_KEEPINTVL TCP_LINGER2 TCP_MAXRT TCP_MAXSEG
 785         TCP_MD5SIG TCP_NODELAY TCP_NOOPT TCP_NOPUSH TCP_QUICKACK
 786         TCP_SACK_ENABLE TCP_STDURG TCP_SYNCNT TCP_WINDOW_CLAMP
 787
 788         IN6ADDR_ANY IN6ADDR_LOOPBACK
 789
 790         IPV6_ADDRFROM IPV6_ADD_MEMBERSHIP IPV6_DROP_MEMBERSHIP IPV6_JOIN_GROUP
 791         IPV6_LEAVE_GROUP IPV6_MTU IPV6_MTU_DISCOVER IPV6_MULTICAST_HOPS
 792         IPV6_MULTICAST_IF IPV6_MULTICAST_LOOP IPV6_RECVERR IPV6_ROUTER_ALERT
 793         IPV6_UNICAST_HOPS IPV6_V6ONLY
 794
 795         SO_LOCK_FILTER SO_RCVBUFFORCE SO_SNDBUFFORCE
 796
 797         pack_ip_mreq unpack_ip_mreq pack_ip_mreq_source unpack_ip_mreq_source
 798
 799         pack_ipv6_mreq unpack_ipv6_mreq
 800
 801         inet_pton inet_ntop
 802
 803         getaddrinfo getnameinfo
 804
 805         AI_ADDRCONFIG AI_ALL AI_CANONIDN AI_CANONNAME AI_IDN
 806         AI_IDN_ALLOW_UNASSIGNED AI_IDN_USE_STD3_ASCII_RULES AI_NUMERICHOST
 807         AI_NUMERICSERV AI_PASSIVE AI_V4MAPPED
 808
 809         NI_DGRAM NI_IDN NI_IDN_ALLOW_UNASSIGNED NI_IDN_USE_STD3_ASCII_RULES
 810         NI_NAMEREQD NI_NOFQDN NI_NUMERICHOST NI_NUMERICSERV
 811
 812         NIx_NOHOST NIx_NOSERV
 813
 814         EAI_ADDRFAMILY EAI_AGAIN EAI_BADFLAGS EAI_BADHINTS EAI_FAIL EAI_FAMILY
 815         EAI_NODATA EAI_NONAME EAI_PROTOCOL EAI_SERVICE EAI_SOCKTYPE EAI_SYSTEM
 816 );
 817
 818 our %EXPORT_TAGS = (
 819     crlf     => [qw(CR LF CRLF $CR $LF $CRLF)],
 820     addrinfo => [qw(getaddrinfo getnameinfo), grep m/^(?:AI|NI|NIx|EAI)_/, @EXPORT_OK],
 821     all      => [@EXPORT, @EXPORT_OK],
 822 );
 823
 824 BEGIN {
 825     sub CR   () {"\015"}
 826     sub LF   () {"\012"}
 827     sub CRLF () {"\015\012"}
 828
 829     # These are not gni() constants; they're extensions for the perl API
 830     # The definitions in Socket.pm and Socket.xs must match
 831     sub NIx_NOHOST() {1 << 0}
 832     sub NIx_NOSERV() {1 << 1}
 833 }
 834
 835 *CR   = \CR();
 836 *LF   = \LF();
 837 *CRLF = \CRLF();
 838
 839 sub sockaddr_in {
 840     if (@_ == 6 && !wantarray) { # perl5.001m compat; use this && die
 841         my($af, $port, @quad) = @_;
 842         warnings::warn "6-ARG sockaddr_in call is deprecated"
 843             if warnings::enabled();
 844         pack_sockaddr_in($port, inet_aton(join('.', @quad)));
 845     } elsif (wantarray) {
 846         croak "usage:   (port,iaddr) = sockaddr_in(sin_sv)" unless @_ == 1;
 847         unpack_sockaddr_in(@_);
 848     } else {
 849         croak "usage:   sin_sv = sockaddr_in(port,iaddr))" unless @_ == 2;
 850         pack_sockaddr_in(@_);
 851     }
 852 }
 853
 854 sub sockaddr_in6 {
 855     if (wantarray) {
 856         croak "usage:   (port,in6addr,scope_id,flowinfo) = sockaddr_in6(sin6_sv)" unless @_ == 1;
 857         unpack_sockaddr_in6(@_);
 858     }
 859     else {
 860         croak "usage:   sin6_sv = sockaddr_in6(port,in6addr,[scope_id,[flowinfo]])" unless @_ >= 2 and @_ <= 4;
 861         pack_sockaddr_in6(@_);
 862     }
 863 }
 864
 865 sub sockaddr_un {
 866     if (wantarray) {
 867         croak "usage:   (filename) = sockaddr_un(sun_sv)" unless @_ == 1;
 868         unpack_sockaddr_un(@_);
 869     } else {
 870         croak "usage:   sun_sv = sockaddr_un(filename)" unless @_ == 1;
 871         pack_sockaddr_un(@_);
 872     }
 873 }
 874
 875 XSLoader::load(__PACKAGE__, $VERSION);
 876
 877 my %errstr;
 878
 879 if( defined &getaddrinfo ) {
 880     # These are not part of the API, nothing uses them, and deleting them
 881     # reduces the size of %Socket:: by about 12K
 882     delete $Socket::{fake_getaddrinfo};
 883     delete $Socket::{fake_getnameinfo};
 884 } else {
 885     require Scalar::Util;
 886
 887     *getaddrinfo = \&fake_getaddrinfo;
 888     *getnameinfo = \&fake_getnameinfo;
 889
 890     # These numbers borrowed from GNU libc's implementation, but since
 891     # they're only used by our emulation, it doesn't matter if the real
 892     # platform's values differ
 893     my %constants = (
 894         AI_PASSIVE     => 1,
 895         AI_CANONNAME   => 2,
 896         AI_NUMERICHOST => 4,
 897         AI_V4MAPPED    => 8,
 898         AI_ALL         => 16,
 899         AI_ADDRCONFIG  => 32,
 900         # RFC 2553 doesn't define this but Linux does - lets be nice and
 901         # provide it since we can
 902         AI_NUMERICSERV => 1024,
 903
 904         EAI_BADFLAGS   => -1,
 905         EAI_NONAME     => -2,
 906         EAI_NODATA     => -5,
 907         EAI_FAMILY     => -6,
 908         EAI_SERVICE    => -8,
 909
 910         NI_NUMERICHOST => 1,
 911         NI_NUMERICSERV => 2,
 912         NI_NOFQDN      => 4,
 913         NI_NAMEREQD    => 8,
 914         NI_DGRAM       => 16,
 915
 916         # Constants we don't support. Export them, but croak if anyone tries to
 917         # use them
 918         AI_IDN                      => 64,
 919         AI_CANONIDN                 => 128,
 920         AI_IDN_ALLOW_UNASSIGNED     => 256,
 921         AI_IDN_USE_STD3_ASCII_RULES => 512,
 922         NI_IDN                      => 32,
 923         NI_IDN_ALLOW_UNASSIGNED     => 64,
 924         NI_IDN_USE_STD3_ASCII_RULES => 128,
 925
 926         # Error constants we'll never return, so it doesn't matter what value
 927         # these have, nor that we don't provide strings for them
 928         EAI_SYSTEM   => -11,
 929         EAI_BADHINTS => -1000,
 930         EAI_PROTOCOL => -1001
 931     );
 932
 933     foreach my $name ( keys %constants ) {
 934         my $value = $constants{$name};
 935
 936         no strict 'refs';
 937         defined &$name or *$name = sub () { $value };
 938     }
 939
 940     %errstr = (
 941         # These strings from RFC 2553
 942         EAI_BADFLAGS()   => "invalid value for ai_flags",
 943         EAI_NONAME()     => "nodename nor servname provided, or not known",
 944         EAI_NODATA()     => "no address associated with nodename",
 945         EAI_FAMILY()     => "ai_family not supported",
 946         EAI_SERVICE()    => "servname not supported for ai_socktype",
 947     );
 948 }
 949
 950 # The following functions are used if the system does not have a
 951 # getaddrinfo(3) function in libc; and are used to emulate it for the AF_INET
 952 # family
 953
 954 # Borrowed from Regexp::Common::net
 955 my $REGEXP_IPv4_DECIMAL = qr/25[0-5]|2[0-4][0-9]|[0-1]?[0-9]{1,2}/;
 956 my $REGEXP_IPv4_DOTTEDQUAD = qr/$REGEXP_IPv4_DECIMAL\.$REGEXP_IPv4_DECIMAL\.$REGEXP_IPv4_DECIMAL\.$REGEXP_IPv4_DECIMAL/;
 957
 958 sub fake_makeerr
 959 {
 960     my ( $errno ) = @_;
 961     my $errstr = $errno == 0 ? "" : ( $errstr{$errno} || $errno );
 962     return Scalar::Util::dualvar( $errno, $errstr );
 963 }
 964
 965 sub fake_getaddrinfo
 966 {
 967     my ( $node, $service, $hints ) = @_;
 968
 969     $node = "" unless defined $node;
 970
 971     $service = "" unless defined $service;
 972
 973     my ( $family, $socktype, $protocol, $flags ) = @$hints{qw( family socktype protocol flags )};
 974
 975     $family ||= Socket::AF_INET(); # 0 == AF_UNSPEC, which we want too
 976     $family == Socket::AF_INET() or return fake_makeerr( EAI_FAMILY() );
 977
 978     $socktype ||= 0;
 979
 980     $protocol ||= 0;
 981
 982     $flags ||= 0;
 983
 984     my $flag_passive     = $flags & AI_PASSIVE();     $flags &= ~AI_PASSIVE();
 985     my $flag_canonname   = $flags & AI_CANONNAME();   $flags &= ~AI_CANONNAME();
 986     my $flag_numerichost = $flags & AI_NUMERICHOST(); $flags &= ~AI_NUMERICHOST();
 987     my $flag_numericserv = $flags & AI_NUMERICSERV(); $flags &= ~AI_NUMERICSERV();
 988
 989     # These constants don't apply to AF_INET-only lookups, so we might as well
 990     # just ignore them. For AI_ADDRCONFIG we just presume the host has ability
 991     # to talk AF_INET. If not we'd have to return no addresses at all. :)
 992     $flags &= ~(AI_V4MAPPED()|AI_ALL()|AI_ADDRCONFIG());
 993
 994     $flags & (AI_IDN()|AI_CANONIDN()|AI_IDN_ALLOW_UNASSIGNED()|AI_IDN_USE_STD3_ASCII_RULES()) and
 995         croak "Socket::getaddrinfo() does not support IDN";
 996
 997     $flags == 0 or return fake_makeerr( EAI_BADFLAGS() );
 998
 999     $node eq "" and $service eq "" and return fake_makeerr( EAI_NONAME() );
1000
1001     my $canonname;
1002     my @addrs;
1003     if( $node ne "" ) {
1004         return fake_makeerr( EAI_NONAME() ) if( $flag_numerichost and $node !~ m/^$REGEXP_IPv4_DOTTEDQUAD$/ );
1005         ( $canonname, undef, undef, undef, @addrs ) = gethostbyname( $node );
1006         defined $canonname or return fake_makeerr( EAI_NONAME() );
1007
1008         undef $canonname unless $flag_canonname;
1009     }
1010     else {
1011         $addrs[0] = $flag_passive ? Socket::inet_aton( "0.0.0.0" )
1012                                   : Socket::inet_aton( "127.0.0.1" );
1013     }
1014
1015     my @ports; # Actually ARRAYrefs of [ socktype, protocol, port ]
1016     my $protname = "";
1017     if( $protocol ) {
1018         $protname = eval { getprotobynumber( $protocol ) };
1019     }
1020
1021     if( $service ne "" and $service !~ m/^\d+$/ ) {
1022         return fake_makeerr( EAI_NONAME() ) if( $flag_numericserv );
1023         getservbyname( $service, $protname ) or return fake_makeerr( EAI_SERVICE() );
1024     }
1025
1026     foreach my $this_socktype ( Socket::SOCK_STREAM(), Socket::SOCK_DGRAM(), Socket::SOCK_RAW() ) {
1027         next if $socktype and $this_socktype != $socktype;
1028
1029         my $this_protname = "raw";
1030         $this_socktype == Socket::SOCK_STREAM() and $this_protname = "tcp";
1031         $this_socktype == Socket::SOCK_DGRAM()  and $this_protname = "udp";
1032
1033         next if $protname and $this_protname ne $protname;
1034
1035         my $port;
1036         if( $service ne "" ) {
1037             if( $service =~ m/^\d+$/ ) {
1038                 $port = "$service";
1039             }
1040             else {
1041                 ( undef, undef, $port, $this_protname ) = getservbyname( $service, $this_protname );
1042                 next unless defined $port;
1043             }
1044         }
1045         else {
1046             $port = 0;
1047         }
1048
1049         push @ports, [ $this_socktype, eval { scalar getprotobyname( $this_protname ) } || 0, $port ];
1050     }
1051
1052     my @ret;
1053     foreach my $addr ( @addrs ) {
1054         foreach my $portspec ( @ports ) {
1055             my ( $socktype, $protocol, $port ) = @$portspec;
1056             push @ret, {
1057                 family    => $family,
1058                 socktype  => $socktype,
1059                 protocol  => $protocol,
1060                 addr      => Socket::pack_sockaddr_in( $port, $addr ),
1061                 canonname => undef,
1062             };
1063         }
1064     }
1065
1066     # Only supply canonname for the first result
1067     if( defined $canonname ) {
1068         $ret[0]->{canonname} = $canonname;
1069     }
1070
1071     return ( fake_makeerr( 0 ), @ret );
1072 }
1073
1074 sub fake_getnameinfo
1075 {
1076     my ( $addr, $flags, $xflags ) = @_;
1077
1078     my ( $port, $inetaddr );
1079     eval { ( $port, $inetaddr ) = Socket::unpack_sockaddr_in( $addr ) }
1080         or return fake_makeerr( EAI_FAMILY() );
1081
1082     my $family = Socket::AF_INET();
1083
1084     $flags ||= 0;
1085
1086     my $flag_numerichost = $flags & NI_NUMERICHOST(); $flags &= ~NI_NUMERICHOST();
1087     my $flag_numericserv = $flags & NI_NUMERICSERV(); $flags &= ~NI_NUMERICSERV();
1088     my $flag_nofqdn      = $flags & NI_NOFQDN();      $flags &= ~NI_NOFQDN();
1089     my $flag_namereqd    = $flags & NI_NAMEREQD();    $flags &= ~NI_NAMEREQD();
1090     my $flag_dgram       = $flags & NI_DGRAM()   ;    $flags &= ~NI_DGRAM();
1091
1092     $flags & (NI_IDN()|NI_IDN_ALLOW_UNASSIGNED()|NI_IDN_USE_STD3_ASCII_RULES()) and
1093         croak "Socket::getnameinfo() does not support IDN";
1094
1095     $flags == 0 or return fake_makeerr( EAI_BADFLAGS() );
1096
1097     $xflags ||= 0;
1098
1099     my $node;
1100     if( $xflags & NIx_NOHOST ) {
1101         $node = undef;
1102     }
1103     elsif( $flag_numerichost ) {
1104         $node = Socket::inet_ntoa( $inetaddr );
1105     }
1106     else {
1107         $node = gethostbyaddr( $inetaddr, $family );
1108         if( !defined $node ) {
1109             return fake_makeerr( EAI_NONAME() ) if $flag_namereqd;
1110             $node = Socket::inet_ntoa( $inetaddr );
1111         }
1112         elsif( $flag_nofqdn ) {
1113             my ( $shortname ) = split m/\./, $node;
1114             my ( $fqdn ) = gethostbyname $shortname;
1115             $node = $shortname if defined $fqdn and $fqdn eq $node;
1116         }
1117     }
1118
1119     my $service;
1120     if( $xflags & NIx_NOSERV ) {
1121         $service = undef;
1122     }
1123     elsif( $flag_numericserv ) {
1124         $service = "$port";
1125     }
1126     else {
1127         my $protname = $flag_dgram ? "udp" : "";
1128         $service = getservbyport( $port, $protname );
1129         if( !defined $service ) {
1130             $service = "$port";
1131         }
1132     }
1133
1134     return ( fake_makeerr( 0 ), $node, $service );
1135 }
1136
1137 1;