original/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 2012-03-24 "GNU" "Linux Programmer's Manual"
  13 .SH NAME
  14 rtnetlink \- macros to manipulate rtnetlink messages
  15 .SH SYNOPSIS
  16 .B #include <asm/types.h>
  17 .br
  18 .B #include <linux/netlink.h>
  19 .br
  20 .B #include <linux/rtnetlink.h>
  21 .br
  22 .B #include <sys/socket.h>
  23
  24 .BI "rtnetlink_socket = socket(AF_NETLINK, int " socket_type \
  25 ", NETLINK_ROUTE);"
  26 .sp
  27 .BI "int RTA_OK(struct rtattr *" rta ", int " rtabuflen );
  28 .sp
  29 .BI "void *RTA_DATA(struct rtattr *" rta );
  30 .sp
  31 .BI "unsigned int RTA_PAYLOAD(struct rtattr *" rta );
  32 .sp
  33 .BI "struct rtattr *RTA_NEXT(struct rtattr *" rta \
  34 ", unsigned int " rtabuflen );
  35 .sp
  36 .BI "unsigned int RTA_LENGTH(unsigned int " length );
  37 .sp
  38 .BI "unsigned int RTA_SPACE(unsigned int "length );
  39 .SH DESCRIPTION
  40 All
  41 .BR rtnetlink (7)
  42 messages consist of a
  43 .BR netlink (7)
  44 message header and appended attributes.
  45 The attributes should be manipulated only using the macros provided here.
  46 .PP
  47 .BI RTA_OK( rta ", " attrlen )
  48 returns true if
  49 .I rta
  50 points to a valid routing attribute;
  51 .I attrlen
  52 is the running length of the attribute buffer.
  53 When not true then you must assume there are no more attributes in the
  54 message, even if
  55 .I attrlen
  56 is nonzero.
  57 .PP
  58 .BI RTA_DATA( rta )
  59 returns a pointer to the start of this attribute's data.
  60 .PP
  61 .BI RTA_PAYLOAD( rta )
  62 returns the length of this attribute's data.
  63 .PP
  64 .BI RTA_NEXT( rta ", " attrlen )
  65 gets the next attribute after
  66 .IR rta .
  67 Calling this macro will update
  68 .IR attrlen .
  69 You should use
  70 .B RTA_OK
  71 to check the validity of the returned pointer.
  72 .PP
  73 .BI RTA_LENGTH( len )
  74 returns the length which is required for
  75 .I len
  76 bytes of data plus the header.
  77 .PP
  78 .BI RTA_SPACE( len )
  79 returns the amount of space which will be needed in a message with
  80 .I len
  81 bytes of data.
  82 .SH CONFORMING TO
  83 These macros are nonstandard Linux extensions.
  84 .SH BUGS
  85 This manual page is incomplete.
  86 .SH EXAMPLE
  87 .\" FIXME ? would be better to use libnetlink in the EXAMPLE code here
  88
  89 Creating a rtnetlink message to set the MTU of a device:
  90 .nf
  91     #include <linux/rtnetlink.h>
  92
  93     ...
  94
  95     struct {
  96         struct nlmsghdr  nh;
  97         struct ifinfomsg if;
  98         char             attrbuf[512];
  99     } req;
 100
 101     struct rtattr *rta;
 102     unsigned int mtu = 1000;
 103
 104     int rtnetlink_sk = socket(AF_NETLINK, SOCK_DGRAM, NETLINK_ROUTE);
 105
 106     memset(&req, 0, sizeof(req));
 107     req.nh.nlmsg_len = NLMSG_LENGTH(sizeof(struct ifinfomsg));
 108     req.nh.nlmsg_flags = NLM_F_REQUEST;
 109     req.nh.nlmsg_type = RTM_NEWLINK;
 110     req.if.ifi_family = AF_UNSPEC;
 111     req.if.ifi_index = INTERFACE_INDEX;
 112     req.if.ifi_change = 0xffffffff; /* ??? */
 113     rta = (struct rtattr *)(((char *) &req) +
 114                              NLMSG_ALIGN(req.nh.nlmsg_len));
 115     rta\->rta_type = IFLA_MTU;
 116     rta\->rta_len = RTA_LENGTH(sizeof(unsigned int));
 117     req.n.nlmsg_len = NLMSG_ALIGN(req.nh.nlmsg_len) +
 118                                   RTA_LENGTH(sizeof(mtu));
 119     memcpy(RTA_DATA(rta), &mtu, sizeof(mtu));
 120     send(rtnetlink_sk, &req, req.nh.nlmsg_len);
 121 .fi
 122 .SH SEE ALSO
 123 .BR netlink (3),
 124 .BR netlink (7),
 125 .BR rtnetlink (7)
 126 .SH COLOPHON
 127 This page is part of release 3.67 of the Linux
 128 .I man-pages
 129 project.
 130 A description of the project,
 131 information about reporting bugs,
 132 and the latest version of this page,
 133 can be found at
 134 \%http://www.kernel.org/doc/man\-pages/.