home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Internet Tools 1993 July / Internet Tools.iso / RockRidge / ip / manage / snmp / cmu-snmp1.0 / man / snmp_api.3 next >
Encoding:
Text File  |  1989-09-19  |  8.0 KB  |  286 lines
  1. .\* /***********************************************************
  2. .\"     Copyright 1989 by Carnegie Mellon University
  3. .\" 
  4. .\"                       All Rights Reserved
  5. .\" 
  6. .\" Permission to use, copy, modify, and distribute this software and its 
  7. .\" documentation for any purpose and without fee is hereby granted, 
  8. .\" provided that the above copyright notice appear in all copies and that
  9. .\" both that copyright notice and this permission notice appear in 
  10. .\" supporting documentation, and that the name of CMU not be
  11. .\" used in advertising or publicity pertaining to distribution of the
  12. .\" software without specific, written prior permission.  
  13. .\" 
  14. .\" CMU DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
  15. .\" ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL
  16. .\" CMU BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR
  17. .\" ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
  18. .\" WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
  19. .\" ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
  20. .\" SOFTWARE.
  21. .\" ******************************************************************/
  22. .TH SNMP_API 3 "Sept 17, 1989"
  23. .UC 5
  24. .SH NAME
  25. snmp_open, snmp_close, snmp_send, snmp_read, snmp_free_pdu, snmp_select_info, snmp_timeout \- send and receive SNMP messages
  26. .SH SYNOPSIS
  27. .B "#include <sys/types>
  28. .br
  29. .B "#include <netinet/in.h>
  30. .br
  31. .B "#include <sys/time.h>
  32. .br
  33. .B #include """snmp.h""
  34. .br
  35. .B #include """snmp_impl.h""
  36. .br
  37. .B #include """asn1.h""
  38. .br
  39. .B #include """snmp_api.c""
  40. .PP
  41. .B "extern int snmp_errno;
  42. .PP
  43. .B "struct snmp_session *snmp_open(session)
  44. .br
  45. .B "struct snmp_session *session;
  46. .PP
  47. .B "int snmp_close(session)
  48. .br
  49. .B "struct snmp_session *session;
  50. .PP
  51. .B "int snmp_send(session, pdu)
  52. .br
  53. .B "struct snmp_session *session;
  54. .br
  55. .B "struct snmp_pdu *pdu;
  56. .PP
  57. .B "void snmp_read(fdset)
  58. .br
  59. .B "fd_set *fdset;
  60. .PP
  61. .B "int snmp_select_info(numfds, fdset, timeout, block)
  62. .br
  63. .B "int *numfds;
  64. .br
  65. .B "fd_set *fdset;
  66. .br
  67. .B "struct timeval *timeout;
  68. .br
  69. .B "int *block;
  70. .PP
  71. .B "void snmp_timeout()
  72. .PP
  73. .B "void snmp_free_pdu(pdu)
  74. .br
  75. .B "struct snmp_pdu *pdu;
  76. .PP
  77. .SH DESCRIPTION
  78. .I Snmp_open, snmp_close,
  79. and
  80. .I snmp_send
  81. each take as input a pointer to an object with the
  82. following structure.  In addition,
  83. .I snmp_open
  84. also returns a pointer to an object with this structure.
  85. This structure contains information for a set of transactions that
  86. will share similar transport characteristics.
  87. .RS
  88. .PP
  89. .nf
  90. typedef struct sockaddr_in  ipaddr;
  91.  
  92. struct snmp_session {
  93.     u_char  *community;    /* community for outgoing requests. */
  94.     int        community_len;  /* Length of community name. */
  95.     int        retries;    /* Number of retries before timeout. */
  96.     long    timeout;    /* Number of uS until first timeout, then exponential backoff */
  97.     char    *peername;    /* Domain name or dotted IP address of default peer */
  98.     u_short remote_port;/* UDP port number of peer. */
  99.     u_short local_port; /* My UDP port number, 0 for default, picked randomly */
  100.  
  101.     /* Authentication function or NULL if null authentication is used */
  102.     u_char  *(*authenticator)();
  103.  
  104.     int        (*callback)();  /* Function to interpret incoming data */
  105.  
  106.     /* Pointer to data that the callback function may consider important */
  107.     void    *callback_magic;
  108. };
  109.  
  110. /*
  111.  * Set fields in session and pdu to the following to get a default or unconfigured value.
  112.  */
  113. #define SNMP_DEFAULT_COMMUNITY_LEN  0/* for default community name */
  114. #define SNMP_DEFAULT_RETRIES        -1
  115. #define SNMP_DEFAULT_TIMEOUT        -1
  116. #define SNMP_DEFAULT_REMPORT        0
  117. #define SNMP_DEFAULT_REQID        0
  118. #define SNMP_DEFAULT_ERRSTAT        -1
  119. #define SNMP_DEFAULT_ERRINDEX        -1
  120. #define SNMP_DEFAULT_ADDRESS        0
  121. #define SNMP_DEFAULT_PEERNAME        NULL
  122. #define SNMP_DEFAULT_ENTERPRISE_LENGTH    0
  123. #define SNMP_DEFAULT_TIME        0
  124.  
  125. /*
  126.  * This routine must be supplied by the application:
  127.  *
  128.  * u_char *authenticator(pdu, length, community, community_len)
  129.  * u_char *pdu;        The rest of the PDU to be authenticated
  130.  * int *length;        The length of the PDU (updated by the authenticator)
  131.  * u_char *community;    The community name to authenticate under.
  132.  * int    community_len    The length of the community name.
  133.  *
  134.  * Returns the authenticated pdu, or NULL if authentication failed.
  135.  * If null authentication is used, the authenticator in snmp_session can be
  136.  * set to NULL(0).
  137.  */
  138.  
  139. /*
  140.  * This routine must be supplied by the application:
  141.  *
  142.  * int callback(operation, session, reqid, pdu, magic)
  143.  * int operation;
  144.  * struct snmp_session *session;    The session authenticated under.
  145.  * int reqid;                The request id of this pdu (0 for TRAP)
  146.  * struct snmp_pdu *pdu;        The pdu information.
  147.  * void *magic                A link to the data for this routine.
  148.  *
  149.  * Returns 1 if request was successful, 0 if it should be kept pending.
  150.  * Any data in the pdu must be copied because it will be freed elsewhere.
  151.  * Operations are defined below:
  152.  */
  153. #define RECEIVED_MESSAGE   1
  154. #define TIMED_OUT       2
  155. .ft R
  156. .ad
  157. .fi
  158. .RE
  159. .PP
  160. .I Snmp_send
  161. and
  162. .I snmp_free_pdu
  163. each take as input a pointer to an object with the
  164. following structure.
  165. This structure contains information that describes a transaction
  166. that will be performed over an open session.
  167. .RS
  168. .PP
  169. .nf
  170. struct snmp_pdu {
  171.     ipaddr  address;    /* Address of peer */
  172.  
  173.     int        command;    /* Type of this PDU */
  174.  
  175.     u_long  reqid;    /* Request id */
  176.     u_long  errstat;    /* Error status */
  177.     u_long  errindex;    /* Error index */
  178.  
  179.     /* Trap information */
  180.     oid        *enterprise;/* System OID */
  181.     int        enterprise_length;
  182.     ipaddr  agent_addr;    /* address of object generating trap */
  183.     int        trap_type;    /* trap type */
  184.     int        specific_type;  /* specific type */
  185.     u_long  time;    /* Uptime */
  186.  
  187.     struct variable_list *variables;
  188. };
  189.  
  190.  
  191. struct variable_list {
  192.     struct variable_list *next_variable;    /* NULL for last variable */
  193.     oid        *name;  /* Object identifier of variable */
  194.     int        name_length;    /* number of subid's in name */
  195.     u_char  type;   /* ASN type of variable */
  196.     union { /* value of variable */
  197.     long    *integer;
  198.     u_char    *string;
  199.     oid    *objid;
  200.     } val;
  201.     int        val_len;
  202. };
  203. .ft R
  204. .ad
  205. .fi
  206. .RE
  207. .PP
  208. .I Snmp_read, snmp_select_info,
  209. and
  210. .I snmp_timeout
  211. provide an interface for the use of the
  212. .IR select (2)
  213. system call so that SNMP transactions can occur asynchronously.
  214. .PP
  215. .I Snmp_select_info
  216. is given the information that would have been passed to
  217. .I select
  218. in the absence of SNMP.  For example, this might include window update information.
  219. This information is modified so that SNMP will get the service it requires from the
  220. call to
  221. .I select.
  222. In this case,
  223. .I numfds, fdset,
  224. and
  225. .I timeout
  226. correspond to the
  227. .I nfds, readfds,
  228. and
  229. .I timeout
  230. arguments to
  231. .I select,
  232. respectively.  The only exception is that timeout must always point to an allocated (but perhaps uninitialized)
  233. .I struct timeval.
  234. If
  235. .I timeout
  236. would have been passed as NULL,
  237. .I block
  238. is set to true, and
  239. .I timeout
  240. is treated as undefined.  This same rule applies upon return from
  241. .I snmp_select_info.
  242. .PP
  243. After calling
  244. .I snmp_select_info, select
  245. is called with the returned data.  When select returns,
  246. .I snmp_read
  247. is called with the
  248. .I fd_set
  249. returned from
  250. .I select.
  251. This will read all SNMP sockets with input.
  252. If
  253. .I select
  254. times out,
  255. .I snmp_timeout
  256. should be called to see if the timeout was intended for SNMP.
  257. .SH DIAGNOSTICS
  258. .PP
  259. Error return status from 
  260. .I snmp_open
  261. is indicated by return of a null pointer.
  262. Error return status from 
  263. .I snmp_close
  264. and
  265. .I snmp_send
  266. is indicated by return of 0.  A successful status will return a 1.
  267. The external integer
  268. .IR snmp_errno
  269. may then be checked to see what type of error has occurred
  270. .PP
  271. .IR snmp_errno
  272. can have the following values:
  273. .RS
  274. .IP SNMPERR_GENERR \w'SNMPERR_BAD_LOCPORT'u+2n
  275. A generic error occurred.
  276. .IP SNMPERR_BAD_LOCPORT \w'SNMPERR_BAD_LOCPORT'u+2n
  277. The local port was bad because it had already been
  278. allocated or permission was denied.
  279. .IP SNMPERR_BAD_ADDRESS \w'SNMPERR_BAD_LOCPORT'u+2n
  280. The host name or address given was not useable.
  281. .IP SNMPERR_BAD_SESSION \w'SNMPERR_BAD_SESSION'u+2n
  282. The specified session was not open.
  283. .RE
  284. .SH "SEE ALSO"
  285. select(2), snmp_api.h
  286.