src/lxc/nl.h

   1 /*
   2  * lxc: linux Container library
   3  *
   4  * (C) Copyright IBM Corp. 2007, 2008
   5  *
   6  * Authors:
   7  * Daniel Lezcano <dlezcano at fr.ibm.com>
   8  *
   9  * This library is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Lesser General Public
  11  * License as published by the Free Software Foundation; either
  12  * version 2.1 of the License, or (at your option) any later version.
  13  *
  14  * This library is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public
  20  * License along with this library; if not, write to the Free Software
  21  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  22  */
  23 #ifndef __nl_h
  24 #define __nl_h
  25
  26 /*
  27  * Use this as a good size to allocate generic netlink messages
  28  */
  29 #ifndef PAGE_SIZE
  30 #define PAGE_SIZE 4096
  31 #endif
  32 #define NLMSG_GOOD_SIZE (2*PAGE_SIZE)
  33 #define NLMSG_TAIL(nmsg) \
  34         ((struct rtattr *) (((void *) (nmsg)) + NLMSG_ALIGN((nmsg)->nlmsg_len)))
  35 #define NLA_DATA(na) ((void *)((char*)(na) + NLA_HDRLEN))
  36 #define NLA_NEXT_ATTR(attr) ((void *)((char *)attr) + NLA_ALIGN(attr->nla_len))
  37
  38 /*
  39  * struct nl_handler : the handler for netlink sockets, this structure
  40  *  is used all along the netlink socket life cycle to specify the
  41  *  netlink socket to be used.
  42  *
  43  * @fd: the file descriptor of the netlink socket
  44  * @seq: the sequence number of the netlink messages
  45  * @local: the bind address
  46  * @peer: the peer address
  47  */
  48 struct nl_handler {
  49         int fd;
  50         int seq;
  51         struct sockaddr_nl local;
  52         struct sockaddr_nl peer;
  53 };
  54
  55 /*
  56  * struct nlmsg : the netlink message structure, it consists just
  57  *  on a definition for a nlmsghdr. This message is to be used to
  58  *  be allocated with netlink_alloc.
  59  * @nlmsghdr : a pointer to a netlink message header, this field
  60  *   _must_ be always the first field of this structure
  61  */
  62 struct nlmsg {
  63         struct nlmsghdr nlmsghdr;
  64 };
  65
  66 /*
  67  * netlink_open : open a netlink socket, the function will
  68  *  fill the handler with the right value
  69  *
  70  * @handler: a netlink handler to be used all along the netlink
  71  *  socket life cycle
  72  * @protocol: specify the protocol to be used when opening the
  73  *  netlink socket
  74  *
  75  * Return 0 on success, < 0 otherwise
  76  */
  77 int netlink_open(struct nl_handler *handler, int protocol);
  78
  79 /*
  80  * netlink_close : close a netlink socket, after this call,
  81  *  the handler is no longer valid
  82  *
  83  * @handler: a handler to the netlink socket
  84  *
  85  * Returns 0 on success, < 0 otherwise
  86  */
  87 int netlink_close(struct nl_handler *handler);
  88
  89 /*
  90  * netlink_rcv : receive a netlink message from the kernel.
  91  *  It is up to the caller to manage the allocation of the
  92  *  netlink message
  93  *
  94  * @handler: a handler to the netlink socket
  95  * @nlmsg: a netlink message
  96  *
  97  * Returns 0 on success, < 0 otherwise
  98  */
  99 int netlink_rcv(struct nl_handler *handler, struct nlmsg *nlmsg);
 100
 101 /*
 102  * netlink_send: send a netlink message to the kernel. It is up
 103  *  to the caller to manage the allocate of the netlink message
 104  *
 105  * @handler: a handler to the netlink socket
 106  * @nlmsg: a netlink message
 107  *
 108  * Returns 0 on success, < 0 otherwise
 109  */
 110 int netlink_send(struct nl_handler *handler, struct nlmsg *nlmsg);
 111
 112 /*
 113  * netlink_transaction: send a request to the kernel and read the response.
 114  *  This is useful for transactional protocol. It is up to the caller
 115  *  to manage the allocation of the netlink message.
 116  *
 117  * @handler: a handler to a opened netlink socket
 118  * @request: a netlink message pointer containing the request
 119  * @answer: a netlink message pointer to receive the result
 120  *
 121  * Returns 0 on success, < 0 otherwise
 122  */
 123 int netlink_transaction(struct nl_handler *handler,
 124                         struct nlmsg *request, struct nlmsg *anwser);
 125
 126 /*
 127  * nla_put_string: copy a null terminated string to a netlink message
 128  *  attribute
 129  *
 130  * @nlmsg: the netlink message to be filled
 131  * @attr: the attribute name of the string
 132  * @string: a null terminated string to be copied to the netlink message
 133  *
 134  * Returns 0 on success, < 0 otherwise
 135  */
 136 int nla_put_string(struct nlmsg *nlmsg, int attr, const char *string);
 137
 138 /*
 139  * nla_put_buffer: copy a buffer with a specified size to a netlink
 140  * message attribute
 141  *
 142  * @nlmsg: the netlink message to be filled
 143  * @attr: the attribute name of the string
 144  * @data: a pointer to a buffer
 145  * @size: the size of the buffer
 146  *
 147  * Returns 0 on success, < 0 otherwise
 148  */
 149 int nla_put_buffer(struct nlmsg *nlmsg, int attr,
 150                    const void *data, size_t size);
 151
 152 /*
 153  * nla_put_u32: copy an integer to a netlink message attribute
 154  *
 155  * @nlmsg: the netlink message to be filled
 156  * @attr: the attribute name of the integer
 157  * @string: an integer  to be copied to the netlink message
 158  *
 159  * Returns 0 on success, < 0 otherwise
 160  */
 161 int nla_put_u32(struct nlmsg *nlmsg, int attr, int value);
 162
 163 /*
 164  * nla_put_u16: copy an integer to a netlink message attribute
 165  *
 166  * @nlmsg: the netlink message to be filled
 167  * @attr: the attribute name of the unsigned 16-bit value
 168  * @value: 16-bit attribute data value to be copied to the netlink message
 169  *
 170  * Returns 0 on success, < 0 otherwise
 171  */
 172 int nla_put_u16(struct nlmsg *nlmsg, int attr, ushort value);
 173
 174 /*
 175  * nla_put_attr: add an attribute name to a netlink
 176  *
 177  * @nlmsg: the netlink message to be filled
 178  * @attr: the attribute name of the integer
 179  *
 180  * Returns 0 on success, < 0 otherwise
 181  */
 182 int nla_put_attr(struct nlmsg *nlmsg, int attr);
 183
 184 /*
 185  * nla_begin_nested: begin the nesting attribute
 186  *
 187  * @nlmsg: the netlink message to be filled
 188  * @attr: the netsted attribute name
 189  *
 190  * Returns current nested pointer to be reused
 191  * to nla_end_nested.
 192  */
 193 struct rtattr *nla_begin_nested(struct nlmsg *nlmsg, int attr);
 194
 195 /*
 196  * nla_end_nested: end the nesting attribute
 197  *
 198  * @nlmsg: the netlink message
 199  * @nested: the nested pointer
 200  *
 201  * Returns the current
 202  */
 203 void nla_end_nested(struct nlmsg *nlmsg, struct rtattr *attr);
 204
 205 /*
 206  * nlmsg_allocate : allocate a netlink message. The netlink format message
 207  *  is a header, a padding, a payload and a padding again.
 208  *  When a netlink message is allocated, the size specify the
 209  *  payload we want. So the real size of the allocated message
 210  *  is sizeof(header) + sizeof(padding) + payloadsize + sizeof(padding),
 211  *  in other words, the function will allocate more than specified. When
 212  *  the buffer is allocated, the content is zeroed.
 213  *  The function will also fill the field nlmsg_len with computed size.
 214  *  If the allocation must be for the specified size, just use malloc.
 215  *
 216  * @size: the size of the payload to be allocated
 217  *
 218  * Returns a pointer to the newly allocated netlink message, NULL otherwise
 219  */
 220 struct nlmsg *nlmsg_alloc(size_t size);
 221
 222 /*
 223  * nlmsg_free : free a previously allocate message
 224  *
 225  * @nlmsg: the netlink message to be freed
 226  */
 227 void nlmsg_free(struct nlmsg *nlmsg);
 228
 229 /*
 230  * nlmsg_data : returns a pointer to the data contained in the netlink message
 231  *
 232  * @nlmsg : the netlink message to get the data
 233  *
 234  * Returns a pointer to the netlink data or NULL if there is no data
 235  */
 236 void *nlmsg_data(struct nlmsg *nlmsg);
 237
 238
 239 #endif