ref: 8be7f27b758ef9ef818f68db0d8bcb7b038eae0e
dir: /sys/man/2/ip/
.TH IP 2
.SH NAME
eipfmt, parseip, parseipmask, parseipandmask, v4parseip, parseether, myipaddr, myetheraddr, maskip, equivip4, equivip6, defmask, isv4, v4tov6, v6tov4, nhgetv, nhgetl, nhgets, hnputv, hnputl, hnputs, ptclbsum, readipifc, iplocalonifc, ipremoteonifc \- Internet Protocol addressing
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.br
.B #include <ip.h>
.PP
.B
int eipfmt(Fmt*)
.PP
.B
vlong parseip(uchar *ipaddr, char *str)
.PP
.B
vlong parseipmask(uchar *ipaddr, char *str, int v4)
.PP
.B
vlong parseipandmask(uchar *ipaddr, uchar *ipmask, char *ipstr, char *maskstr)
.PP
.B
char* v4parseip(uchar *ipaddr, char *str)
.PP
.B
int parseether(uchar *eaddr, char *str)
.PP
.B
int myetheraddr(uchar *eaddr, char *dev)
.PP
.B
int myipaddr(uchar *ipaddr, char *net)
.PP
.B
void maskip(uchar *from, uchar *mask, uchar *to)
.PP
.B
int equivip4(uchar *ipaddr1, uchar *ipaddr2)
.PP
.B
int equivip6(uchar *ipaddr1, uchar *ipaddr2)
.PP
.B
uchar* defmask(uchar *ipaddr)
.PP
.B
int isv4(uchar *ipaddr)
.PP
.B
void v4tov6(uchar *ipv6, uchar *ipv4)
.PP
.B
int v6tov4(uchar *ipv4, uchar *ipv6)
.PP
.B
ushort nhgets(void *p)
.PP
.B
uint nhgetl(void *p)
.PP
.B
uvlong nhgetv(void *p)
.PP
.B
void hnputs(void *p, ushort v)
.PP
.B
void hnputl(void *p, uint v)
.PP
.B
void hnputv(void *p, uvlong v)
.PP
.B
ushort ptclbsum(uchar *a, int n)
.PP
.B
Ipifc* readipifc(char *net, Ipifc *ifc, int index)
.PP
.B
Iplifc* iplocalonifc(Ipifc *ifc, uchar *ip)
.PP
.B
Iplifc* ipremoteonifc(Ipifc *ifc, uchar *ip)
.PP
.B
uchar IPv4bcast[IPaddrlen];
.PP
.B
uchar IPv4allsys[IPaddrlen];
.PP
.B
uchar IPv4allrouter[IPaddrlen];
.PP
.B
uchar IPallbits[IPaddrlen];
.PP
.B
uchar IPnoaddr[IPaddrlen];
.PP
.B
uchar v4prefix[IPaddrlen];
.SH DESCRIPTION
These routines are used by Internet Protocol (IP) programs to
manipulate IP and Ethernet addresses.
Plan 9, by default, uses V6-format IP addresses. Since V4
addresses fit into the V6 space, all IP addresses can be represented.
IP addresses are stored as a string of 16
.B unsigned
.BR chars ,
Ethernet
addresses as 6
.B unsigned
.BR chars .
Either V4 or V6 string representation can be used for IP addresses.
For V4 addresses, the representation can be (up to) 4 decimal
integers from 0 to 255 separated by periods.
For V6 addresses, the representation is (up to) 8 hex integers
from 0x0 to 0xFFFF separated by colons.
Strings of 0 integers can be elided using two colons.
For example,
.B FFFF::1111
is equivalent to
.BR FFFF:0:0:0:0:0:0:1111 .
The string representation for IP masks is a superset of the
address representation. It includes slash notation that indicates
the number of leading 1 bits in the mask. Thus, a
V4 class C mask can be represented as
.BR FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FF00 ,
.BR 255.255.255.0 ,
or
.BR /120.
The string representation of Ethernet addresses is exactly
12 hexadecimal digits.
.PP
.I Eipfmt
is a
.IR print (2)
formatter for Ethernet (verb
.BR E )
addresses,
IP V6 (verb
.BR I )
addresses,
IP V4 (verb
.BR V )
addresses,
and IP V6 (verb
.BR M )
masks.
.PP
.I Parseip
converts a string pointed to by
.I str
to a 16-byte IP address starting at
.IR ipaddr .
As a concession to backwards compatibility,
if the string is a V4 address, the return value
is an unsigned long integer containing the big-endian V4 address.
If not, the return value is 6.
.PP
.I Parseipmask
converts a string pointed to by
.I str
to a 16-byte IP mask starting at
.IR ipaddr .
It too returns an unsigned long big-endian V4 address or 6.
.I Parseipmask
accepts a mask in
.BI / prefixlen
slash notation. When the
.IR v4
argument is non-zero, then
.I prefixlen
in range [0..32] is offset by 96 to yield a mask for a V4 address.
.PP
.I Parseipandmask
combines
.I parseip
and
.I parseipmask
into a single call, interpreting the mask in context of the
supplied IP address type.
The returned IP mask is
.B /128
when
.I maskstr
is
.BR nil .
.PP
All three functions return -1 on errors.
.PP
.I V4parseip
converts a string pointed to by
.I str
to a 4-byte V4 IP address starting at
.IR ipaddr .
.PP
.I Myipaddr
returns the first valid IP address in
the IP stack rooted at
.IR net .
.PP
.I Parseether
converts a string pointed to by
.I str
to a 6-byte Ethernet address starting at
.IR eaddr .
.I Myetheraddr
reads the Ethernet address string from file
.IB dev /addr
and parses it into
.IR eaddr .
Both routines return a negative number on errors.
.PP
.I Maskip
places the bit-wise AND of the IP addresses pointed
to by its first two arguments into the buffer pointed
to by the third.
.PP
.I Equivip
returns non-zero if the IP addresses pointed to by its two
arguments are equal.
.I Equivip4
operates on v4 addresses,
.I equivip6
operates on v6 addresses.
.PP
.I Defmask
returns the standard class A, B, or C mask for
.IR ipaddr .
.PP
.I Isv4
returns non-zero if the V6 address is in the V4 space, that is,
if it starts with
.BR 0:0:0:0:0:0:FFFF .
.I V4tov6
converts the 4-byte V4 address,
.IR v4ip ,
to a V6 address and puts the result in
.IR v6ip .
.I V6tov4
converts the V6 address,
.IR v6ip ,
to a 4-byte V4 address and puts the result in
.IR v4ip .
.PP
.IR Hnputs ,
.I hnputl
and
.I hnputv
are used to store 16-bit, 32-bit, and 64-bit integers, respectively, into IP big-endian form.
.IR Nhgets ,
.I nhgetl
and
.I nhgetv
convert big-endian 2, 4 and 8 byte quantities into integers (or
.IR uvlong s).
.PP
.I Pctlbsum
returns the one's complement checksum used in IP protocols, typically invoked as
.IP
.EX
hnputs(hdr->cksum, ~ptclbsum(data, len) & 0xffff);
.EE
.PP
A number of standard IP addresses in V6 format are also defined. They are:
.TF IPv4allrouter
.TP
.B IPv4bcast
the V4 broadcast address
.TP
.B IPv4allsys
the V4 all systems multicast address
.TP
.B IPv4allrouter
the V4 all routers multicast address
.TP
.B IPallbits
the V6 all bits on address
.TP
.B IPnoaddr
the V6 null address, all zeros
.TP
.B v4prefix
the IP V6 prefix to all embedded V4 addresses
.PD
.PP
.I Readipifc
returns information about
a particular interface
.RI ( index
>= 0)
or all IP interfaces
.RI ( index
< 0)
configured under a mount point
.IR net ,
default
.BR /net .
Each interface is described by one
.I Ipifc
structure which in turn points to a linked list of
.IR Iplifc
structures describing the addresses assigned
to this interface.
If the list
.IR ifc
is supplied,
that list is freed.
Thus, subsequent calls can be used
to free the list returned by the previous call.
.I Ipifc
is:
.PP
.EX
typedef struct Ipifc
{
Ipifc *next;
Iplifc *lifc; /* local addressses */
/* per ip interface */
int index; /* number of interface in ipifc dir */
char dev[64]; /* associated physical device */
int mtu; /* max transfer unit */
uchar sendra6; /* on == send router adv */
uchar recvra6; /* on == rcv router adv */
ulong pktin; /* packets read */
ulong pktout; /* packets written */
ulong errin; /* read errors */
ulong errout; /* write errors */
Ipv6rp rp; /* route advertisement params */
} Ipifc;
.EE
.PP
.I Iplifc
is:
.PP
.EX
struct Iplifc
{
Iplifc *next;
uchar ip[IPaddrlen];
uchar mask[IPaddrlen];
uchar net[IPaddrlen]; /* ip & mask */
ulong preflt; /* preferred lifetime */
ulong validlt; /* valid lifetime */
};
.EE
.PP
.I Ipv6rp
is:
.PP
.EX
struct Ipv6rp
{
int mflag;
int oflag;
int maxraint; /* max route adv interval */
int minraint; /* min route adv interval */
int linkmtu;
int reachtime;
int rxmitra;
int ttl;
int routerlt;
};
.EE
.PP
.I Dev
contains the first 64 bytes of the device configured with this
interface.
.I Net
is
.IB ip & mask
if the network is multipoint or
the remote address if the network is
point to point.
.PP
.I Iplocalonifc
looks up the first local address structure
that matches
.I ip
on the interface
.IR ifc .
E.g.
.I ip
is one of our local ip addresses on
.IR ifc .
.I Ipremoteonifc
returns the first local address structure
with a subnet that
.I ip
is a member of.
E.g.
.I ip
is a directly reachable remote address on
.IR ifc .
Both
.I iplocalonifc
and
.I ipremoteonifc
return
.B nil
when no local address structrue is found.
.SH SOURCE
.B /sys/src/libip
.SH SEE ALSO
.IR print (2),
.IR ip (3)