.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "addrinfo 3"
.TH addrinfo 3 2023-07-29 "perl v5.38.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Net::addrinfo \- interface to POSIX getaddrinfo(3) and related
constants, structures and functions.
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\& use Net::addrinfo;
\& my $ainfo = getaddrinfo("www.marzot.net");
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This Perl module is designed to implement and export functionality
related to the POSIX \fBgetaddrinfo\fR\|(3) system call. The Net::addrinfo
data object is provided with field name accsessor functions, similarly
named to the the C data structure definition in \fInetdb.h\fR. The
\&\fBgetaddrinfo\fR\|(3), \fBgai_strerror\fR\|(3) calls, and related constants are
exported.
.PP
The \fBgetaddrinfo()\fR routine mimics the POSIX documented funtion (see
system man page \fBgetaddrinfo\fR\|(3)).
.PP
On success the \fBgetaddrinfo()\fR will return an array of Net::addrinfo
data objects.
.PP
In scalar context \fBgetaddrinfo()\fR will return the first element from the
Net::addrinfo array.
.PP
In case of error, a numeric error code is returned.
.PP
The error code may be passed to \fBgai_strerror()\fR to get a string
representation of the error.
.PP
New Net::addrinfo objects may be created with the package constructor
and any number (or none) of the fields may be specified.
.PP
.Vb 6
\&   flags => scalar integer
\&   family => scalar integer (e.g., AF_INET,m AF_INET6, etc.)
\&   socktype => scalar integer (e.g., SOCK_DGRAM, SOCK_STREAM, etc.)
\&   protocol => scalar integer (e.g., IPPROTO_UDP, IPPROTO_TCP, etc.)
\&   addrlen => scalar integer (can be computed by length($self\->addr))
\&   addr => packed bytes (e.g., $self\->addr(inet_aton("192.168.1.1")); )
.Ve
.PP
Flags may be set in the structure so that it may be used as a 'hint'
parameter to the \fBgetaddrinfo()\fR function. See exported \f(CW@AI_FLAGS\fR for
list of acceptable constants.
.PP
(Note: a special scalar integer field, 'val_status', is provided in
support of DNSSEC aware addrinfo results (see Net::DNS::SEC::Validator))
.SH EXAMPLES
.IX Header "EXAMPLES"
.Vb 2
\& use Net::addrinfo;
\& use Socket qw(:all);
\&
\& my $hint = new Net::addrinfo(flags => AI_CANONNAME,
\&                              family => AF_INET, 
\&                              socktype => SOCK_DGRAM);
\&
\& my (@ainfo) = getaddrinfo("www.marzot.net", "http", $hint);
\&
\& foreach $ainfo (@ainfo) {
\&    if (ref $ainfo eq \*(AqNet::addrinfo\*(Aq) {
\&       print $ainfo\->stringify(), "\en";
\&       print "addr = ", inet_ntoa($ainfo\->addr), "\en";
\&       ...
\&       connect(SH, $ainfo\->addr);
\&     } else {
\&        print "Error($ainfo):", gai_strerror($ainfo), "\en";
\&     }
\& }
.Ve
.SH NOTE
.IX Header "NOTE"
One should not rely on the internal representation of this class.
.SH AUTHOR
.IX Header "AUTHOR"
G. S. Marzot (marz@users.sourceforge.net)
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
.Vb 3
\&   Copyright (c) 2006 G. S. Marzot. All rights reserved.  This program
\&   is free software; you can redistribute it and/or modify it under
\&   the same terms as Perl itself.
\&
\&   Copyright (c) 2006\-2008 SPARTA, Inc.  All Rights Reserved.  This program
\&   is free software; you can redistribute it and/or modify it under
\&   the same terms as Perl itself.
.Ve