man3/rtnetlink.3

   1 .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM_ONE_PARA)
   4 .\" Permission is granted to distribute possibly modified copies
   5 .\" of this page provided the header is included verbatim,
   6 .\" and in case of nontrivial modification author and date
   7 .\" of the modification is added to the header.
   8 .\" %%%LICENSE_END
   9 .\"
  10 .\" $Id: rtnetlink.3,v 1.2 1999/05/18 10:35:10 freitag Exp $
  11 .\"
  12 .TH RTNETLINK 3 2021-03-22 "GNU" "Linux Programmer's Manual"
  13 .SH NAME
  14 rtnetlink \- macros to manipulate rtnetlink messages
  15 .SH SYNOPSIS
  16 .nf
  17 .B #include <asm/types.h>
  18 .B #include <linux/netlink.h>
  19 .B #include <linux/rtnetlink.h>
  20 .B #include <sys/socket.h>
  21 .PP
  22 .BI "rtnetlink_socket = socket(AF_NETLINK, int " socket_type \
  23 ", NETLINK_ROUTE);"
  24 .PP
  25 .BI "int RTA_OK(struct rtattr *" rta ", int " rtabuflen );
  26 .PP
  27 .BI "void *RTA_DATA(struct rtattr *" rta );
  28 .BI "unsigned int RTA_PAYLOAD(struct rtattr *" rta );
  29 .PP
  30 .BI "struct rtattr *RTA_NEXT(struct rtattr *" rta \
  31 ", unsigned int " rtabuflen );
  32 .PP
  33 .BI "unsigned int RTA_LENGTH(unsigned int " length );
  34 .BI "unsigned int RTA_SPACE(unsigned int "length );
  35 .fi
  36 .SH DESCRIPTION
  37 All
  38 .BR rtnetlink (7)
  39 messages consist of a
  40 .BR netlink (7)
  41 message header and appended attributes.
  42 The attributes should be manipulated only using the macros provided here.
  43 .PP
  44 .BI RTA_OK( rta ", " attrlen )
  45 returns true if
  46 .I rta
  47 points to a valid routing attribute;
  48 .I attrlen
  49 is the running length of the attribute buffer.
  50 When not true then you must assume there are no more attributes in the
  51 message, even if
  52 .I attrlen
  53 is nonzero.
  54 .PP
  55 .BI RTA_DATA( rta )
  56 returns a pointer to the start of this attribute's data.
  57 .PP
  58 .BI RTA_PAYLOAD( rta )
  59 returns the length of this attribute's data.
  60 .PP
  61 .BI RTA_NEXT( rta ", " attrlen )
  62 gets the next attribute after
  63 .IR rta .
  64 Calling this macro will update
  65 .IR attrlen .
  66 You should use
  67 .B RTA_OK
  68 to check the validity of the returned pointer.
  69 .PP
  70 .BI RTA_LENGTH( len )
  71 returns the length which is required for
  72 .I len
  73 bytes of data plus the header.
  74 .PP
  75 .BI RTA_SPACE( len )
  76 returns the amount of space which will be needed in a message with
  77 .I len
  78 bytes of data.
  79 .SH CONFORMING TO
  80 These macros are nonstandard Linux extensions.
  81 .SH BUGS
  82 This manual page is incomplete.
  83 .SH EXAMPLES
  84 .\" FIXME . ? would be better to use libnetlink in the EXAMPLE code here
  85 Creating a rtnetlink message to set the MTU of a device:
  86 .PP
  87 .in +4n
  88 .EX
  89 #include <linux/rtnetlink.h>
  90
  91 \&...
  92
  93 struct {
  94     struct nlmsghdr  nh;
  95     struct ifinfomsg if;
  96     char             attrbuf[512];
  97 } req;
  98
  99 struct rtattr *rta;
 100 unsigned int mtu = 1000;
 101
 102 int rtnetlink_sk = socket(AF_NETLINK, SOCK_DGRAM, NETLINK_ROUTE);
 103
 104 memset(&req, 0, sizeof(req));
 105 req.nh.nlmsg_len = NLMSG_LENGTH(sizeof(req.if));
 106 req.nh.nlmsg_flags = NLM_F_REQUEST;
 107 req.nh.nlmsg_type = RTM_NEWLINK;
 108 req.if.ifi_family = AF_UNSPEC;
 109 req.if.ifi_index = INTERFACE_INDEX;
 110 req.if.ifi_change = 0xffffffff; /* ??? */
 111 rta = (struct rtattr *)(((char *) &req) +
 112                          NLMSG_ALIGN(req.nh.nlmsg_len));
 113 rta\->rta_type = IFLA_MTU;
 114 rta\->rta_len = RTA_LENGTH(sizeof(mtu));
 115 req.nh.nlmsg_len = NLMSG_ALIGN(req.nh.nlmsg_len) +
 116                               RTA_LENGTH(sizeof(mtu));
 117 memcpy(RTA_DATA(rta), &mtu, sizeof(mtu));
 118 send(rtnetlink_sk, &req, req.nh.nlmsg_len, 0);
 119 .EE
 120 .in
 121 .SH SEE ALSO
 122 .BR netlink (3),
 123 .BR netlink (7),
 124 .BR rtnetlink (7)