Changeset b10460a in mainline for uspace/lib


Ignore:
Timestamp:
2015-08-07T21:39:00Z (10 years ago)
Author:
Jiri Svoboda <jiri@…>
Branches:
lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export
Children:
b688fd8
Parents:
6accc5cf
Message:

Add missing docblocks in network code.

Location:
uspace/lib
Files:
5 edited

Legend:

Unmodified
Added
Removed

  • uspace/lib/c/generic/inet/endpoint.c

    r6accc5cf rb10460a  
    3636#include <mem.h>
    3737
     38/** Initialize endpoint structure.
     39 *
     40 * Sets any address, any port number.
     41 *
     42 * @param ep Endpoint
     43 */
    3844void inet_ep_init(inet_ep_t *ep)
    3945{
    … …  
    4147}
    4248
     49/** Initialize endpoint pair structure.
     50 *
     51 * Sets any address, any port number for both local and remote sides.
     52 *
     53 * @param ep2 Endpoint pair
     54 */
    4355void inet_ep2_init(inet_ep2_t *ep2)
    4456{

  • uspace/lib/c/generic/inet/tcp.c

    r6accc5cf rb10460a  
    4444static int tcp_conn_fibril(void *);
    4545
    46 /** Incoming TCP connection info */
     46/** Incoming TCP connection info
     47 *
     48 * Used to pass information about incoming TCP connection to the connection
     49 * fibril
     50 */
    4751typedef struct {
     52        /** Listener who received the connection */
    4853        tcp_listener_t *lst;
     54        /** Incoming connection */
    4955        tcp_conn_t *conn;
    5056} tcp_in_conn_t;
    5157
     58/** Create callback connection from TCP service.
     59 *
     60 * @param tcp TCP service
     61 * @return EOK on success or negative error code
     62 */
    5263static int tcp_callback_create(tcp_t *tcp)
    5364{
    … …  
    6778}
    6879
     80/** Create TCP client instance.
     81 *
     82 * @param  rtcp Place to store pointer to new TCP client
     83 * @return EOK on success, ENOMEM if out of memory, EIO if service
     84 *         cannot be contacted
     85 */
    6986int tcp_create(tcp_t **rtcp)
    7087{
    … …  
    111128}
    112129
     130/** Destroy TCP client instance.
     131 *
     132 * @param tcp TCP client
     133 */
    113134void tcp_destroy(tcp_t *tcp)
    114135{
    … …  
    126147}
    127148
     149/** Create new TCP connection
     150 *
     151 * @param tcp   TCP client instance
     152 * @param id    Connection ID
     153 * @param cb    Callbacks
     154 * @param arg   Callback argument
     155 * @param rconn Place to store pointer to new connection
     156 *
     157 * @return EOK on success, ENOMEM if out of memory
     158 */
    128159static int tcp_conn_new(tcp_t *tcp, sysarg_t id, tcp_cb_t *cb, void *arg,
    129160    tcp_conn_t **rconn)
    … …  
    150181}
    151182
     183/** Create new TCP connection.
     184 *
     185 * Open a connection to the specified destination. This function returns
     186 * even before the connection is established (or not). When the connection
     187 * is established, @a cb->connected is called. If the connection fails,
     188 * @a cb->conn_failed is called. Alternatively, the caller can call
     189 * @c tcp_conn_wait_connected() to wait for connection to complete or fail.
     190 * Other callbacks are available to monitor the changes in connection state.
     191 *
     192 * @a epp must specify the remote address and port. Both local address and
     193 * port are optional. If local address is not specified, address selection
     194 * will take place. If local port number is not specified, a suitable
     195 * free dynamic port number will be allocated.
     196 *
     197 * @param tcp   TCP client
     198 * @param epp   Internet endpoint pair
     199 * @param cb    Callbacks
     200 * @param arg   Argument to callbacks
     201 * @param rconn Place to store pointer to new connection
     202 *
     203 * @return EOK on success or negative error code.
     204 */
    152205int tcp_conn_create(tcp_t *tcp, inet_ep2_t *epp, tcp_cb_t *cb, void *arg,
    153206    tcp_conn_t **rconn)
    … …  
    186239}
    187240
     241/** Destroy TCP connection.
     242 *
     243 * Destroy TCP connection. The caller should destroy all connections
     244 * he created before destroying the TCP client and before terminating.
     245 *
     246 * @param conn TCP connection
     247 */
    188248void tcp_conn_destroy(tcp_conn_t *conn)
    189249{
    … …  
    203263}
    204264
     265/** Get connection based on its ID.
     266 *
     267 * @param tcp   TCP client
     268 * @param id    Connection ID
     269 * @param rconn Place to store pointer to connection
     270 *
     271 * @return EOK on success, EINVAL if no connection with the given ID exists
     272 */
    205273static int tcp_conn_get(tcp_t *tcp, sysarg_t id, tcp_conn_t **rconn)
    206274{
    … …  
    215283}
    216284
     285/** Get the user/callback argument for a connection.
     286 *
     287 * @param conn TCP connection
     288 * @return User argument associated with connection
     289 */
    217290void *tcp_conn_userptr(tcp_conn_t *conn)
    218291{
    … …  
    220293}
    221294
     295/** Create a TCP connection listener.
     296 *
     297 * A listener listens for connections on the set of endpoints specified
     298 * by @a ep. Each time a new incoming connection is established,
     299 * @a lcb->new_conn is called (and passed @a larg). Also, the new connection
     300 * will have callbacks set to @a cb and argument to @a arg.
     301 *
     302 * @a ep must specify a valid port number. @a ep may specify an address
     303 * or link to listen on. If it does not, the listener will listen on
     304 * all links/addresses.
     305 *
     306 * @param tcp  TCP client
     307 * @param ep   Internet endpoint
     308 * @param lcb  Listener callbacks
     309 * @param larg Listener callback argument
     310 * @param cb   Connection callbacks for every new connection
     311 * @param arg  Connection argument for every new connection
     312 * @param rlst Place to store pointer to new listener
     313 *
     314 * @return EOK on success or negative error code
     315 */
    222316int tcp_listener_create(tcp_t *tcp, inet_ep_t *ep, tcp_listen_cb_t *lcb,
    223317    void *larg, tcp_cb_t *cb, void *arg, tcp_listener_t **rlst)
    … …  
    265359}
    266360
     361/** Destroy TCP connection listener.
     362 *
     363 * @param lst Listener
     364 */
    267365void tcp_listener_destroy(tcp_listener_t *lst)
    268366{
    … …  
    282380}
    283381
     382/** Get TCP connection listener based on its ID.
     383 *
     384 * @param tcp TCP client
     385 * @param id  Listener ID
     386 * @param rlst Place to store pointer to listener
     387 *
     388 * @return EOK on success, EINVAL if no listener with the given ID is found
     389 */
    284390static int tcp_listener_get(tcp_t *tcp, sysarg_t id, tcp_listener_t **rlst)
    285391{
    … …  
    294400}
    295401
     402/** Get callback/user argument associated with listener.
     403 *
     404 * @param lst Listener
     405 * @return Callback/user argument
     406 */
    296407void *tcp_listener_userptr(tcp_listener_t *lst)
    297408{
    … …  
    299410}
    300411
     412/** Wait until connection is either established or connection fails.
     413 *
     414 * Can be called after calling tcp_conn_create() to block until connection
     415 * either completes or fails. If the connection fails, EIO is returned.
     416 * In this case the connection still exists, but is in a failed
     417 * state.
     418 *
     419 * @param conn Connection
     420 * @return EOK if connection is established, EIO otherwise
     421 */
    301422int tcp_conn_wait_connected(tcp_conn_t *conn)
    302423{
    … …  
    315436}
    316437
     438/** Send data over TCP connection.
     439 *
     440 * @param conn  Connection
     441 * @param data  Data
     442 * @param bytes Data size in bytes
     443 *
     444 * @return EOK on success or negative error code
     445 */
    317446int tcp_conn_send(tcp_conn_t *conn, const void *data, size_t bytes)
    318447{
    … …  
    340469}
    341470
    342 
     471/** Send FIN.
     472 *
     473 * Send FIN, indicating no more data will be send over the connection.
     474 *
     475 * @param conn Connection
     476 * @return EOK on success or negative error code
     477 */
    343478int tcp_conn_send_fin(tcp_conn_t *conn)
    344479{
    … …  
    352487}
    353488
     489/** Push connection.
     490 *
     491 * @param conn Connection
     492 * @return EOK on success or negative error code
     493 */
    354494int tcp_conn_push(tcp_conn_t *conn)
    355495{
    … …  
    363503}
    364504
     505/** Reset connection.
     506 *
     507 * @param conn Connection
     508 * @return EOK on success or negative error code
     509 */
    365510int tcp_conn_reset(tcp_conn_t *conn)
    366511{
    … …  
    374519}
    375520
     521/** Read received data from connection without blocking.
     522 *
     523 * If any received data is pending on the connection, up to @a bsize bytes
     524 * are copied to @a buf and the acutal number is stored in @a *nrecv.
     525 * The entire buffer of @a bsize bytes is filled except when less data
     526 * is currently available or FIN is received. EOK is returned.
     527 *
     528 * If no received data is pending, returns EAGAIN.
     529 *
     530 * @param conn Connection
     531 * @param buf  Buffer
     532 * @param bsize Buffer size
     533 * @param nrecv Place to store actual number of received bytes
     534 *
     535 * @return EOK on success, EAGAIN if no received data is pending, or other
     536 *         negative error code in case of other error
     537 */
    376538int tcp_conn_recv(tcp_conn_t *conn, void *buf, size_t bsize, size_t *nrecv)
    377539{
    … …  
    408570}
    409571
    410 int tcp_conn_recv_wait(tcp_conn_t *conn, void *buf, size_t bsize, size_t *nrecv)
     572/** Read received data from connection with blocking.
     573 *
     574 * Wait for @a bsize bytes of data to be received and copy them to
     575 * @a buf. Less data may be returned if FIN is received on the connection.
     576 * The actual If any received data is written to @a *nrecv and EOK
     577 * is returned on success.
     578 *
     579 * @param conn Connection
     580 * @param buf  Buffer
     581 * @param bsize Buffer size
     582 * @param nrecv Place to store actual number of received bytes
     583 *
     584 * @return EOK on success or negative error code
     585 */
     586int tcp_conn_recv_wait(tcp_conn_t *conn, void *buf, size_t bsize,
     587    size_t *nrecv)
    411588{
    412589        async_exch_t *exch;
    … …  
    450627}
    451628
     629/** Connection established event.
     630 *
     631 * @param tcp TCP client
     632 * @param iid Call ID
     633 * @param icall Call data
     634 */
    452635static void tcp_ev_connected(tcp_t *tcp, ipc_callid_t iid, ipc_call_t *icall)
    453636{
    … …  
    472655}
    473656
     657/** Connection failed event.
     658 *
     659 * @param tcp TCP client
     660 * @param iid Call ID
     661 * @param icall Call data
     662 */
    474663static void tcp_ev_conn_failed(tcp_t *tcp, ipc_callid_t iid, ipc_call_t *icall)
    475664{
    … …  
    494683}
    495684
     685/** Connection reset event.
     686 *
     687 * @param tcp TCP client
     688 * @param iid Call ID
     689 * @param icall Call data
     690 */
    496691static void tcp_ev_conn_reset(tcp_t *tcp, ipc_callid_t iid, ipc_call_t *icall)
    497692{
    … …  
    516711}
    517712
     713/** Data available event.
     714 *
     715 * @param tcp TCP client
     716 * @param iid Call ID
     717 * @param icall Call data
     718 */
    518719static void tcp_ev_data(tcp_t *tcp, ipc_callid_t iid, ipc_call_t *icall)
    519720{
    … …  
    539740}
    540741
     742/** Urgent data event.
     743 *
     744 * @param tcp TCP client
     745 * @param iid Call ID
     746 * @param icall Call data
     747 */
    541748static void tcp_ev_urg_data(tcp_t *tcp, ipc_callid_t iid, ipc_call_t *icall)
    542749{
    … …  
    544751}
    545752
     753/** New connection event.
     754 *
     755 * @param tcp TCP client
     756 * @param iid Call ID
     757 * @param icall Call data
     758 */
    546759static void tcp_ev_new_conn(tcp_t *tcp, ipc_callid_t iid, ipc_call_t *icall)
    547760{
    … …  
    590803}
    591804
     805/** Callback connection handler.
     806 *
     807 * @param iid Connect call ID
     808 * @param icall Connect call data
     809 * @param arg Argument, TCP client
     810 */
    592811static void tcp_cb_conn(ipc_callid_t iid, ipc_call_t *icall, void *arg)
    593812{
    … …  
    636855}
    637856
    638 /** Fibril for handling incoming TCP connection in background */
     857/** Fibril for handling incoming TCP connection in background.
     858 *
     859 * @param arg Argument, incoming connection information (@c tcp_in_conn_t)
     860 */
    639861static int tcp_conn_fibril(void *arg)
    640862{

  • uspace/lib/c/generic/inet/udp.c

    r6accc5cf rb10460a  
    4343static void udp_cb_conn(ipc_callid_t, ipc_call_t *, void *);
    4444
     45/** Create callback connection from UDP service.
     46 *
     47 * @param udp UDP service
     48 * @return EOK on success or negative error code
     49 */
    4550static int udp_callback_create(udp_t *udp)
    4651{
    … …  
    6065}
    6166
     67/** Create UDP client instance.
     68 *
     69 * @param  rudp Place to store pointer to new UDP client
     70 * @return EOK on success, ENOMEM if out of memory, EIO if service
     71 *         cannot be contacted
     72 */
    6273int udp_create(udp_t **rudp)
    6374{
    … …  
    103114}
    104115
     116/** Destroy UDP client instance.
     117 *
     118 * @param udp UDP client
     119 */
    105120void udp_destroy(udp_t *udp)
    106121{
    … …  
    118133}
    119134
    120 int udp_assoc_create(udp_t *udp, inet_ep2_t *ep2, udp_cb_t *cb, void *arg,
     135/** Create new UDP association.
     136 *
     137 * Create a UDP association that allows sending and receiving messages.
     138 *
     139 * @a epp may specify remote address and port, in which case only messages
     140 * from that remote endpoint will be received. Also, that remote endpoint
     141 * is used as default when @c NULL is passed as destination to
     142 * udp_assoc_send_msg.
     143 *
     144 * @a epp may specify a local link or address. If it does not, the association
     145 * will listen on all local links/addresses. If @a epp does not specify
     146 * a local port number, a free dynamic port number will be allocated.
     147 *
     148 * The caller is informed about incoming data by invoking @a cb->recv_msg
     149 *
     150 * @param udp    UDP client
     151 * @param epp    Internet endpoint pair
     152 * @param cb     Callbacks
     153 * @param arg    Argument to callbacks
     154 * @param rassoc Place to store pointer to new association
     155 *
     156 * @return EOK on success or negative error code.
     157 */
     158int udp_assoc_create(udp_t *udp, inet_ep2_t *epp, udp_cb_t *cb, void *arg,
    121159    udp_assoc_t **rassoc)
    122160{
    … …  
    131169        exch = async_exchange_begin(udp->sess);
    132170        aid_t req = async_send_0(exch, UDP_ASSOC_CREATE, &answer);
    133         sysarg_t rc = async_data_write_start(exch, (void *)ep2,
     171        sysarg_t rc = async_data_write_start(exch, (void *)epp,
    134172            sizeof(inet_ep2_t));
    135173        async_exchange_end(exch);
    … …  
    161199}
    162200
     201/** Destroy UDP association.
     202 *
     203 * Destroy UDP association. The caller should destroy all associations
     204 * he created before destroying the UDP client and before terminating.
     205 *
     206 * @param assoc UDP association
     207 */
    163208void udp_assoc_destroy(udp_assoc_t *assoc)
    164209{
    … …  
    178223}
    179224
     225/** Send message via UDP association.
     226 *
     227 * @param assoc Association
     228 * @param dest  Destination endpoint or @c NULL to use association's remote ep.
     229 * @param data  Message data
     230 * @param bytes Message size in bytes
     231 *
     232 * @return EOK on success or negative error code
     233 */
    180234int udp_assoc_send_msg(udp_assoc_t *assoc, inet_ep_t *dest, void *data,
    181235    size_t bytes)
    … …  
    211265}
    212266
     267/** Get the user/callback argument for an association.
     268 *
     269 * @param assoc UDP association
     270 * @return User argument associated with association
     271 */
    213272void *udp_assoc_userptr(udp_assoc_t *assoc)
    214273{
    … …  
    216275}
    217276
     277/** Get size of received message in bytes.
     278 *
     279 * Assuming jumbo messages can be received, the caller first needs to determine
     280 * the size of the received message by calling this function, then they can
     281 * read the message piece-wise using udp_rmsg_read().
     282 *
     283 * @param rmsg Received message
     284 * @return Size of received message in bytes
     285 */
    218286size_t udp_rmsg_size(udp_rmsg_t *rmsg)
    219287{
    … …  
    221289}
    222290
     291/** Read part of received message.
     292 *
     293 * @param rmsg  Received message
     294 * @param off   Start offset
     295 * @param buf   Buffer for storing data
     296 * @param bsize Buffer size
     297 *
     298 * @return EOK on success or negative error code.
     299 */
    223300int udp_rmsg_read(udp_rmsg_t *rmsg, size_t off, void *buf, size_t bsize)
    224301{
    … …  
    245322}
    246323
     324/** Get remote endpoint of received message.
     325 *
     326 * Place the remote endpoint (the one from which the message was supposedly
     327 * sent) to @a ep.
     328 *
     329 * @param rmsg Received message
     330 * @param ep   Place to store remote endpoint
     331 */
    247332void udp_rmsg_remote_ep(udp_rmsg_t *rmsg, inet_ep_t *ep)
    248333{
    … …  
    250335}
    251336
     337/** Get type of received ICMP error message.
     338 *
     339 * @param rerr Received error message
     340 * @return Error message type
     341 */
    252342uint8_t udp_rerr_type(udp_rerr_t *rerr)
    253343{
    … …  
    255345}
    256346
     347/** Get code of received ICMP error message.
     348 *
     349 * @param rerr Received error message
     350 * @return Error message code
     351 */
    257352uint8_t udp_rerr_code(udp_rerr_t *rerr)
    258353{
    … …  
    260355}
    261356
     357/** Get information about the next received message from UDP service.
     358 *
     359 * @param udp  UDP client
     360 * @param rmsg Place to store message information
     361 *
     362 * @return EOK on success or negative error code
     363 */
    262364static int udp_rmsg_info(udp_t *udp, udp_rmsg_t *rmsg)
    263365{
    … …  
    288390}
    289391
     392/** Discard next received message in UDP service.
     393 *
     394 * @param udp UDP client
     395 * @return EOK on success or negative error code
     396 */
    290397static int udp_rmsg_discard(udp_t *udp)
    291398{
    … …  
    299406}
    300407
     408/** Get association based on its ID.
     409 *
     410 * @param udp    UDP client
     411 * @param id     Association ID
     412 * @param rassoc Place to store pointer to association
     413 *
     414 * @return EOK on success, EINVAL if no association with the given ID exists
     415 */
    301416static int udp_assoc_get(udp_t *udp, sysarg_t id, udp_assoc_t **rassoc)
    302417{
    … …  
    311426}
    312427
     428/** Handle 'data' event, i.e. some message(s) arrived.
     429 *
     430 * For each received message, get information about it, call @c recv_msg
     431 * callback and discard it.
     432 *
     433 * @param udp UDP client
     434 * @param iid IPC message ID
     435 * @param icall IPC message
     436 */
    313437static void udp_ev_data(udp_t *udp, ipc_callid_t iid, ipc_call_t *icall)
    314438{
    … …  
    340464}
    341465
     466/** UDP service callback connection.
     467 *
     468 * @param iid Connect message ID
     469 * @param icall Connect message
     470 * @param arg Argument, UDP client
     471 */
    342472static void udp_cb_conn(ipc_callid_t iid, ipc_call_t *icall, void *arg)
    343473{

  • uspace/lib/nettl/src/amap.c

    r6accc5cf rb10460a  
    3636 * Manages allocations of endpoints / endpoint pairs (corresponding to
    3737 * UDP associations, TCP listeners and TCP connections)
     38 *
     39 * An association map contains different types of entries, based on which
     40 * set of attributes (key) they specify. In order from most specific to the
     41 * least specific one:
     42 *
     43 *  - repla (remote endpoint, local address)
     44 *  - laddr (local address)
     45 *  - llink (local link)
     46 *  - unspec (unspecified)
     47 *
     48 * In the unspecified case only the local port is known and the entry matches
     49 * all remote and local addresses.
    3850 */
    3951
    … …  
    4759#include <stdlib.h>
    4860
     61/** Create association map.
     62 *
     63 * @param rmap Place to store pointer to new association map
     64 * @return EOk on success, ENOMEM if out of memory
     65 */
    4966int amap_create(amap_t **rmap)
    5067{
    … …  
    7390}
    7491
     92/** Destroy association map.
     93 *
     94 * @param map Association map
     95 */
    7596void amap_destroy(amap_t *map)
    7697{
    … …  
    79100}
    80101
    81 /** Find exact repla */
     102/** Find exact repla.
     103 *
     104 * Find repla (remote endpoint, local address) entry by exact match.
     105 *
     106 * @param map Association map
     107 * @param rep Remote endpoint
     108 * @param la  Local address
     109 * @param rrepla Place to store pointer to repla
     110 *
     111 * @return EOK on success, ENOENT if not found
     112 */
    82113static int amap_repla_find(amap_t *map, inet_ep_t *rep, inet_addr_t *la,
    83114    amap_repla_t **rrepla)
    … …  
    113144}
    114145
     146/** Insert repla.
     147 *
     148 * Insert new repla (remote endpoint, local address) entry to association map.
     149 *
     150 * @param amap   Association map
     151 * @param rep    Remote endpoint
     152 * @param la     Local address
     153 * @param rrepla Place to store pointer to new repla
     154 *
     155 * @return EOK on success, ENOMEM if out of memory
     156 */
    115157static int amap_repla_insert(amap_t *map, inet_ep_t *rep, inet_addr_t *la,
    116158    amap_repla_t **rrepla)
    … …  
    139181}
    140182
     183/** Remove repla from association map.
     184 *
     185 * Remove repla (remote endpoint, local address) from association map.
     186 *
     187 * @param map   Association map
     188 * @param repla Repla
     189 */
    141190static void amap_repla_remove(amap_t *map, amap_repla_t *repla)
    142191{
    … …  
    146195}
    147196
    148 /** Find exact laddr */
     197/** Find exact laddr.
     198 *
     199 * Find laddr (local address) entry by exact match.
     200 *
     201 * @param map    Association map
     202 * @param addr   Address
     203 * @param rladdr Place to store pointer to laddr entry
     204 *
     205 * @return EOK on success, ENOENT if not found.
     206 */
    149207static int amap_laddr_find(amap_t *map, inet_addr_t *addr,
    150208    amap_laddr_t **rladdr)
    … …  
    161219}
    162220
     221/** Insert laddr.
     222 *
     223 * Insert new laddr (local address) entry to association map.
     224 *
     225 * @param addr   Local address
     226 * @param rladdr Place to store pointer to new laddr
     227 *
     228 * @return EOK on success, ENOMEM if out of memory
     229 */
    163230static int amap_laddr_insert(amap_t *map, inet_addr_t *addr,
    164231    amap_laddr_t **rladdr)
    … …  
    186253}
    187254
     255/** Remove laddr from association map.
     256 *
     257 * Remove laddr (local address) entry from association map.
     258 *
     259 * @param map   Association map
     260 * @param laddr Laddr entry
     261 */
    188262static void amap_laddr_remove(amap_t *map, amap_laddr_t *laddr)
    189263{
    … …  
    193267}
    194268
    195 /** Find exact llink */
     269/** Find exact llink.
     270 *
     271 * Find llink (local link) entry by exact match.
     272 *
     273 * @param map     Association map
     274 * @param link_id Local link ID
     275 * @param rllink  Place to store pointer to llink entry
     276 *
     277 * @return EOK on success, ENOENT if not found.
     278 */
    196279static int amap_llink_find(amap_t *map, sysarg_t link_id,
    197280    amap_llink_t **rllink)
    … …  
    208291}
    209292
     293/** Insert llink.
     294 *
     295 * Insert new llink (local link) entry to association map.
     296 *
     297 * @param link_id Local link
     298 * @param rllink  Place to store pointer to new llink
     299 *
     300 * @return EOK on success, ENOMEM if out of memory
     301 */
    210302static int amap_llink_insert(amap_t *map, sysarg_t link_id,
    211303    amap_llink_t **rllink)
    … …  
    233325}
    234326
     327/** Remove llink from association map.
     328 *
     329 * Remove llink (local link) entry from association map.
     330 *
     331 * @param map   Association map
     332 * @param llink Llink entry
     333 */
    235334static void amap_llink_remove(amap_t *map, amap_llink_t *llink)
    236335{
    … …  
    240339}
    241340
     341/** Insert endpoint pair into map with repla as key.
     342 *
     343 * If local port number is not specified, it is allocated.
     344 *
     345 * @param map Association map
     346 * @param epp Endpoint pair, possibly with local port inet_port_any
     347 * @param arg arg User value
     348 * @param flags Flags
     349 * @param aepp Place to store actual endpoint pair, possibly with allocated port
     350 *
     351 * @return EOK on success, EEXISTS if conflicting epp exists,
     352 *         ENOMEM if out of memory
     353 */
    242354static int amap_insert_repla(amap_t *map, inet_ep2_t *epp, void *arg,
    243355    amap_flags_t flags, inet_ep2_t *aepp)
    … …  
    272384}
    273385
     386/** Insert endpoint pair into map with laddr as key.
     387 *
     388 * If local port number is not specified, it is allocated.
     389 *
     390 * @param map Association map
     391 * @param epp Endpoint pair, possibly with local port inet_port_any
     392 * @param arg arg User value
     393 * @param flags Flags
     394 * @param aepp Place to store actual endpoint pair, possibly with allocated port
     395 *
     396 * @return EOK on success, EEXISTS if conflicting epp exists,
     397 *         ENOMEM if out of memory
     398 */
    274399static int amap_insert_laddr(amap_t *map, inet_ep2_t *epp, void *arg,
    275400    amap_flags_t flags, inet_ep2_t *aepp)
    … …  
    303428}
    304429
     430/** Insert endpoint pair into map with llink as key.
     431 *
     432 * If local port number is not specified, it is allocated.
     433 *
     434 * @param map Association map
     435 * @param epp Endpoint pair, possibly with local port inet_port_any
     436 * @param arg arg User value
     437 * @param flags Flags
     438 * @param aepp Place to store actual endpoint pair, possibly with allocated port
     439 *
     440 * @return EOK on success, EEXISTS if conflicting epp exists,
     441 *         ENOMEM if out of memory
     442 */
    305443static int amap_insert_llink(amap_t *map, inet_ep2_t *epp, void *arg,
    306444    amap_flags_t flags, inet_ep2_t *aepp)
    … …  
    334472}
    335473
     474/** Insert endpoint pair into map with unspec as key.
     475 *
     476 * If local port number is not specified, it is allocated.
     477 *
     478 * @param map Association map
     479 * @param epp Endpoint pair, possibly with local port inet_port_any
     480 * @param arg arg User value
     481 * @param flags Flags
     482 * @param aepp Place to store actual endpoint pair, possibly with allocated port
     483 *
     484 * @return EOK on success, EEXISTS if conflicting epp exists,
     485 *         ENOMEM if out of memory
     486 */
    336487static int amap_insert_unspec(amap_t *map, inet_ep2_t *epp, void *arg,
    337488    amap_flags_t flags, inet_ep2_t *aepp)
    … …  
    417568}
    418569
     570/** Remove endpoint pair using repla as key from map.
     571 *
     572 * The endpoint pair must be present in the map, otherwise behavior
     573 * is unspecified.
     574 *
     575 * @param map Association map
     576 * @param epp Endpoint pair
     577 */
    419578static void amap_remove_repla(amap_t *map, inet_ep2_t *epp)
    420579{
    … …  
    434593}
    435594
     595/** Remove endpoint pair using laddr as key from map.
     596 *
     597 * The endpoint pair must be present in the map, otherwise behavior
     598 * is unspecified.
     599 *
     600 * @param map Association map
     601 * @param epp Endpoint pair
     602 */
    436603static void amap_remove_laddr(amap_t *map, inet_ep2_t *epp)
    437604{
    … …  
    451618}
    452619
     620/** Remove endpoint pair using llink as key from map.
     621 *
     622 * The endpoint pair must be present in the map, otherwise behavior
     623 * is unspecified.
     624 *
     625 * @param map Association map
     626 * @param epp Endpoint pair
     627 */
    453628static void amap_remove_llink(amap_t *map, inet_ep2_t *epp)
    454629{
    … …  
    468643}
    469644
     645/** Remove endpoint pair using unspec as key from map.
     646 *
     647 * The endpoint pair must be present in the map, otherwise behavior
     648 * is unspecified.
     649 *
     650 * @param map Association map
     651 * @param epp Endpoint pair
     652 */
    470653static void amap_remove_unspec(amap_t *map, inet_ep2_t *epp)
    471654{
    … …  
    473656}
    474657
     658/** Remove endpoint pair from map.
     659 *
     660 * The endpoint pair must be present in the map, otherwise behavior
     661 * is unspecified.
     662 *
     663 * @param map Association map
     664 * @param epp Endpoint pair
     665 */
    475666void amap_remove(amap_t *map, inet_ep2_t *epp)
    476667{

  • uspace/lib/nettl/src/portrng.c

    r6accc5cf rb10460a  
    4646#include <io/log.h>
    4747
     48/** Create port range.
     49 *
     50 * @param rpr Place to store pointer to new port range
     51 * @return EOK on success, ENOMEM if out of memory
     52 */
    4853int portrng_create(portrng_t **rpr)
    4954{
    … …  
    6267}
    6368
     69/** Destroy port range.
     70 *
     71 * @param pr Port range
     72 */
    6473void portrng_destroy(portrng_t *pr)
    6574{
    … …  
    6978}
    7079
     80/** Allocate port number from port range.
     81 *
     82 * @param pr    Port range
     83 * @param pnum  Port number to allocate specific port, or zero to allocate
     84 *              any valid port from range
     85 * @param arg   User argument to set for port
     86 * @param flags Flags, @c pf_allow_system to allow ports from system range
     87 *              to be specified by @a pnum.
     88 * @param apnum Place to store allocated port number
     89 *
     90 * @return EOK on success, ENOENT if no free port number found, EEXISTS
     91 *         if @a pnum is specified but it is already allocated,
     92 *         EINVAL if @a pnum is specified from the system range, but
     93 *         @c pf_allow_system was not set.
     94 */
    7195int portrng_alloc(portrng_t *pr, uint16_t pnum, void *arg,
    7296    portrng_flags_t flags, uint16_t *apnum)
    … …  
    131155}
    132156
     157/** Find allocated port number and return its argument.
     158 *
     159 * @param pr   Port range
     160 * @param pnum Port number
     161 * @param rarg Place to store user argument
     162 *
     163 * @return EOK on success, ENOENT if specified port number is not allocated
     164 */
    133165int portrng_find_port(portrng_t *pr, uint16_t pnum, void **rarg)
    134166{
    … …  
    143175}
    144176
     177/** Free port in port range.
     178 *
     179 * @param pr   Port range
     180 * @param pnum Port number
     181 */
    145182void portrng_free_port(portrng_t *pr, uint16_t pnum)
    146183{
    … …  
    158195}
    159196
     197/** Determine if port range is empty.
     198 *
     199 * @param pr Port range
     200 * @return @c true if no ports are allocated from @a pr, @c false otherwise
     201 */
    160202bool portrng_empty(portrng_t *pr)
    161203{
Note: See TracChangeset for help on using the changeset viewer.