userapps/opensource/net-snmp/man/netsnmp_library.3

   1 .TH "The Net-SNMP library" 3 "5 Mar 2003" "net-snmp" \" -*- nroff -*-
   2 .ad l
   3 .nh
   4 .SH NAME
   5 The Net-SNMP library \-
   6 .SS "Modules"
   7
   8 .in +1c
   9 .ti -1c
  10 .RI "\fBmib parsing and datatype manipulation routines.\fP"
  11 .br
  12 .in -1c
  13 .SS "Data Structures"
  14
  15 .in +1c
  16 .ti -1c
  17 .RI "struct \fBsession_list\fP"
  18 .br
  19 .ti -1c
  20 .RI "struct \fBsnmp_internal_session\fP"
  21 .br
  22 .in -1c
  23 .SS "Defines"
  24
  25 .in +1c
  26 .ti -1c
  27 .RI "#define \fBSNMP_NEED_REQUEST_LIST\fP"
  28 .br
  29 .ti -1c
  30 .RI "#define \fBtimercmp\fP(tvp, uvp, cmp)"
  31 .br
  32 .ti -1c
  33 .RI "#define \fBtimerclear\fP(tvp)   (tvp)->tv_sec = (tvp)->tv_usec = 0"
  34 .br
  35 .ti -1c
  36 .RI "#define \fBMAX_PACKET_LENGTH\fP   (0x7fffffff)"
  37 .br
  38 .ti -1c
  39 .RI "#define \fBNETSNMP_STREAM_QUEUE_LEN\fP   5"
  40 .br
  41 .ti -1c
  42 .RI "#define \fBBSD4_2\fP"
  43 .br
  44 .ti -1c
  45 .RI "#define \fBNFDBITS\fP   (sizeof(fd_mask) * NBBY)"
  46 .br
  47 .ti -1c
  48 .RI "#define \fBFD_SET\fP(n, p)   ((p)->fds_bits[(n)/NFDBITS] |= (1 << ((n) % NFDBITS)))"
  49 .br
  50 .ti -1c
  51 .RI "#define \fBFD_CLR\fP(n, p)   ((p)->fds_bits[(n)/NFDBITS] &= ~(1 << ((n) % NFDBITS)))"
  52 .br
  53 .ti -1c
  54 .RI "#define \fBFD_ISSET\fP(n, p)   ((p)->fds_bits[(n)/NFDBITS] & (1 << ((n) % NFDBITS)))"
  55 .br
  56 .ti -1c
  57 .RI "#define \fBFD_ZERO\fP(p)   memset((p), 0, sizeof(*(p)))"
  58 .br
  59 .ti -1c
  60 .RI "#define \fBDEFAULT_COMMUNITY\fP   'public'"
  61 .br
  62 .ti -1c
  63 .RI "#define \fBDEFAULT_RETRIES\fP   5"
  64 .br
  65 .ti -1c
  66 .RI "#define \fBDEFAULT_TIMEOUT\fP   1000000L"
  67 .br
  68 .ti -1c
  69 .RI "#define \fBDEFAULT_REMPORT\fP   SNMP_PORT"
  70 .br
  71 .ti -1c
  72 .RI "#define \fBDEFAULT_ENTERPRISE\fP   default_enterprise"
  73 .br
  74 .ti -1c
  75 .RI "#define \fBDEFAULT_TIME\fP   0"
  76 .br
  77 .ti -1c
  78 .RI "#define \fBMAXIMUM_PACKET_SIZE\fP   0x7fffffff"
  79 .br
  80 .ti -1c
  81 .RI "#define \fBDEBUGPRINTPDUTYPE\fP(token, type)"
  82 .br
  83 .ti -1c
  84 .RI "#define \fBERROR_STAT_LENGTH\fP   11"
  85 .br
  86 .in -1c
  87 .SS "Typedefs"
  88
  89 .in +1c
  90 .ti -1c
  91 .RI "typedef long \fBfd_mask\fP"
  92 .br
  93 .in -1c
  94 .SS "Functions"
  95
  96 .in +1c
  97 .ti -1c
  98 .RI "int \fBsnmp_build\fP (u_char **pkt, size_t *pkt_len, size_t *offset, netsnmp_session *pss, netsnmp_pdu *pdu)"
  99 .br
 100 .ti -1c
 101 .RI "int \fBsnmp_get_errno\fP (void)"
 102 .br
 103 .ti -1c
 104 .RI "void \fBsnmp_synch_reset\fP (netsnmp_session *notused)"
 105 .br
 106 .ti -1c
 107 .RI "void \fBsnmp_synch_setup\fP (netsnmp_session *notused)"
 108 .br
 109 .ti -1c
 110 .RI "const char * \fBstrerror\fP (int err)"
 111 .br
 112 .ti -1c
 113 .RI "long \fBsnmp_get_next_reqid\fP (void)"
 114 .br
 115 .ti -1c
 116 .RI "long \fBsnmp_get_next_msgid\fP (void)"
 117 .br
 118 .ti -1c
 119 .RI "long \fBsnmp_get_next_sessid\fP (void)"
 120 .br
 121 .ti -1c
 122 .RI "long \fBsnmp_get_next_transid\fP (void)"
 123 .br
 124 .ti -1c
 125 .RI "void \fBsnmp_perror\fP (const char *prog_string)"
 126 .br
 127 .ti -1c
 128 .RI "void \fBsnmp_set_detail\fP (const char *detail_string)"
 129 .br
 130 .ti -1c
 131 .RI "const char * \fBsnmp_api_errstring\fP (int snmp_errnumber)"
 132 .br
 133 .ti -1c
 134 .RI "void \fBsnmp_error\fP (netsnmp_session *psess, int *p_errno, int *p_snmp_errno, char **p_str)"
 135 .br
 136 .ti -1c
 137 .RI "void \fBsnmp_sess_error\fP (void *sessp, int *p_errno, int *p_snmp_errno, char **p_str)"
 138 .br
 139 .ti -1c
 140 .RI "void \fBnetsnmp_sess_log_error\fP (int priority, const char *prog_string, netsnmp_session *ss)"
 141 .br
 142 .ti -1c
 143 .RI "void \fBsnmp_sess_perror\fP (const char *prog_string, netsnmp_session *ss)"
 144 .br
 145 .ti -1c
 146 .RI "void \fBsnmp_sess_init\fP (netsnmp_session *session)"
 147 .br
 148 .ti -1c
 149 .RI "void \fBinit_snmp_enums\fP (void)"
 150 .br
 151 .ti -1c
 152 .RI "void \fBinit_snmp\fP (const char *type)"
 153 .br
 154 .ti -1c
 155 .RI "void \fBsnmp_store\fP (const char *type)"
 156 .br
 157 .ti -1c
 158 .RI "void \fBsnmp_shutdown\fP (const char *type)"
 159 .br
 160 .ti -1c
 161 .RI "netsnmp_session * \fBsnmp_open\fP (netsnmp_session *session)"
 162 .br
 163 .ti -1c
 164 .RI "netsnmp_session * \fBsnmp_open_ex\fP (netsnmp_session *session, int(*fpre_parse)(netsnmp_session *, netsnmp_transport *, void *, int), int(*fparse)(netsnmp_session *, netsnmp_pdu *, u_char *, size_t), int(*fpost_parse)(netsnmp_session *, netsnmp_pdu *, int), int(*fbuild)(netsnmp_session *, netsnmp_pdu *, u_char *, size_t *), int(*frbuild)(netsnmp_session *, netsnmp_pdu *, u_char **, size_t *, size_t *), int(*fcheck)(u_char *, size_t))"
 165 .br
 166 .ti -1c
 167 .RI "int \fBsnmpv3_engineID_probe\fP (struct session_list *slp, netsnmp_session *in_session)"
 168 .br
 169 .ti -1c
 170 .RI "netsnmp_session * \fBsnmp_add\fP (netsnmp_session *in_session, netsnmp_transport *transport, int(*fpre_parse)(netsnmp_session *, netsnmp_transport *, void *, int), int(*fpost_parse)(netsnmp_session *, netsnmp_pdu *, int))"
 171 .br
 172 .ti -1c
 173 .RI "netsnmp_session * \fBsnmp_add_full\fP (netsnmp_session *in_session, netsnmp_transport *transport, int(*fpre_parse)(netsnmp_session *, netsnmp_transport *, void *, int), int(*fparse)(netsnmp_session *, netsnmp_pdu *, u_char *, size_t), int(*fpost_parse)(netsnmp_session *, netsnmp_pdu *, int), int(*fbuild)(netsnmp_session *, netsnmp_pdu *, u_char *, size_t *), int(*frbuild)(netsnmp_session *, netsnmp_pdu *, u_char **, size_t *, size_t *), int(*fcheck)(u_char *, size_t), netsnmp_pdu *(*fcreate_pdu)(netsnmp_transport *, void *, size_t))"
 174 .br
 175 .ti -1c
 176 .RI "void * \fBsnmp_sess_add_ex\fP (netsnmp_session *in_session, netsnmp_transport *transport, int(*fpre_parse)(netsnmp_session *, netsnmp_transport *, void *, int), int(*fparse)(netsnmp_session *, netsnmp_pdu *, u_char *, size_t), int(*fpost_parse)(netsnmp_session *, netsnmp_pdu *, int), int(*fbuild)(netsnmp_session *, netsnmp_pdu *, u_char *, size_t *), int(*frbuild)(netsnmp_session *, netsnmp_pdu *, u_char **, size_t *, size_t *), int(*fcheck)(u_char *, size_t), netsnmp_pdu *(*fcreate_pdu)(netsnmp_transport *, void *, size_t))"
 177 .br
 178 .ti -1c
 179 .RI "void * \fBsnmp_sess_add\fP (netsnmp_session *in_session, netsnmp_transport *transport, int(*fpre_parse)(netsnmp_session *, netsnmp_transport *, void *, int), int(*fpost_parse)(netsnmp_session *, netsnmp_pdu *, int))"
 180 .br
 181 .ti -1c
 182 .RI "void * \fBsnmp_sess_open\fP (netsnmp_session *pss)"
 183 .br
 184 .ti -1c
 185 .RI "int \fBcreate_user_from_session\fP (netsnmp_session *session)"
 186 .br
 187 .ti -1c
 188 .RI "int \fBsnmp_sess_close\fP (void *sessp)"
 189 .br
 190 .ti -1c
 191 .RI "int \fBsnmp_close\fP (netsnmp_session *session)"
 192 .br
 193 .ti -1c
 194 .RI "int \fBsnmp_close_sessions\fP (void)"
 195 .br
 196 .ti -1c
 197 .RI "int \fBsnmpv3_packet_build\fP (netsnmp_session *session, netsnmp_pdu *pdu, u_char *packet, size_t *out_length, u_char *pdu_data, size_t pdu_data_len)"
 198 .br
 199 .ti -1c
 200 .RI "u_char * \fBsnmp_pdu_build\fP (netsnmp_pdu *pdu, u_char *cp, size_t *out_length)"
 201 .br
 202 .ti -1c
 203 .RI "int \fBsnmpv3_parse\fP (netsnmp_pdu *pdu, u_char *data, size_t *length, u_char **after_header, netsnmp_session *sess)"
 204 .br
 205 .ti -1c
 206 .RI "int \fBsnmpv3_make_report\fP (netsnmp_pdu *pdu, int error)"
 207 .br
 208 .ti -1c
 209 .RI "int \fBsnmpv3_get_report_type\fP (netsnmp_pdu *pdu)"
 210 .br
 211 .ti -1c
 212 .RI "int \fBsnmp_pdu_parse\fP (netsnmp_pdu *pdu, u_char *data, size_t *length)"
 213 .br
 214 .ti -1c
 215 .RI "u_char * \fBsnmpv3_scopedPDU_parse\fP (netsnmp_pdu *pdu, u_char *cp, size_t *length)"
 216 .br
 217 .ti -1c
 218 .RI "int \fBsnmp_send\fP (netsnmp_session *session, netsnmp_pdu *pdu)"
 219 .br
 220 .ti -1c
 221 .RI "int \fBsnmp_sess_send\fP (void *sessp, netsnmp_pdu *pdu)"
 222 .br
 223 .ti -1c
 224 .RI "int \fBsnmp_async_send\fP (netsnmp_session *session, netsnmp_pdu *pdu, snmp_callback callback, void *cb_data)"
 225 .br
 226 .ti -1c
 227 .RI "int \fBsnmp_sess_async_send\fP (void *sessp, netsnmp_pdu *pdu, snmp_callback callback, void *cb_data)"
 228 .br
 229 .ti -1c
 230 .RI "void \fBsnmp_free_var\fP (netsnmp_variable_list *var)"
 231 .br
 232 .ti -1c
 233 .RI "void \fBsnmp_free_varbind\fP (netsnmp_variable_list *var)"
 234 .br
 235 .ti -1c
 236 .RI "void \fBsnmp_free_pdu\fP (netsnmp_pdu *pdu)"
 237 .br
 238 .ti -1c
 239 .RI "netsnmp_pdu * \fBsnmp_create_sess_pdu\fP (netsnmp_transport *transport, void *opaque, size_t olength)"
 240 .br
 241 .ti -1c
 242 .RI "void \fBsnmp_read\fP (fd_set *fdset)"
 243 .br
 244 .ti -1c
 245 .RI "int \fB_sess_read\fP (void *sessp, fd_set *fdset)"
 246 .br
 247 .ti -1c
 248 .RI "int \fBsnmp_sess_read\fP (void *sessp, fd_set *fdset)"
 249 .br
 250 .ti -1c
 251 .RI "int \fBsnmp_select_info\fP (int *numfds, fd_set *fdset, struct timeval *timeout, int *block)"
 252 .br
 253 .ti -1c
 254 .RI "int \fBsnmp_sess_select_info\fP (void *sessp, int *numfds, fd_set *fdset, struct timeval *timeout, int *block)"
 255 .br
 256 .ti -1c
 257 .RI "void \fBsnmp_timeout\fP (void)"
 258 .br
 259 .ti -1c
 260 .RI "void \fBsnmp_sess_timeout\fP (void *sessp)"
 261 .br
 262 .ti -1c
 263 .RI "int \fBsnmp_oid_ncompare\fP (const oid *in_name1, size_t len1, const oid *in_name2, size_t len2, size_t max_len)"
 264 .br
 265 .ti -1c
 266 .RI "int \fBsnmp_oid_compare\fP (const oid *in_name1, size_t len1, const oid *in_name2, size_t len2)"
 267 .br
 268 .RI "\fIlexicographical compare two object identifiers.\fP"
 269 .ti -1c
 270 .RI "int \fBsnmp_oidtree_compare\fP (const oid *in_name1, size_t len1, const oid *in_name2, size_t len2)"
 271 .br
 272 .RI "\fICompares 2 OIDs to determine if they are equal up until the shortest length.\fP"
 273 .ti -1c
 274 .RI "int \fBnetsnmp_oid_equals\fP (const oid *in_name1, size_t len1, const oid *in_name2, size_t len2)"
 275 .br
 276 .RI "\fICompares 2 OIDs to determine if they are exactly equal.\fP"
 277 .ti -1c
 278 .RI "int \fBnetsnmp_oid_is_subtree\fP (const oid *in_name1, size_t len1, const oid *in_name2, size_t len2)"
 279 .br
 280 .RI "\fIIdentical to netsnmp_oid_equals, except only the length up to len1 is compared.\fP"
 281 .ti -1c
 282 .RI "int \fBnetsnmp_oid_find_prefix\fP (const oid *in_name1, size_t len1, const oid *in_name2, size_t len2)"
 283 .br
 284 .RI "\fIGiven two OIDs, determine the common prefix to them both.\fP"
 285 .ti -1c
 286 .RI "netsnmp_variable_list * \fBsnmp_pdu_add_variable\fP (netsnmp_pdu *pdu, oid *name, size_t name_length, u_char type, const u_char *value, size_t len)"
 287 .br
 288 .ti -1c
 289 .RI "netsnmp_variable_list * \fBsnmp_varlist_add_variable\fP (netsnmp_variable_list **varlist, oid *name, size_t name_length, u_char type, const u_char *value, size_t len)"
 290 .br
 291 .ti -1c
 292 .RI "int \fBsnmp_add_var\fP (netsnmp_pdu *pdu, oid *name, size_t name_length, char type, const char *value)"
 293 .br
 294 .ti -1c
 295 .RI "void * \fBsnmp_sess_pointer\fP (netsnmp_session *session)"
 296 .br
 297 .ti -1c
 298 .RI "netsnmp_session * \fBsnmp_sess_session\fP (void *sessp)"
 299 .br
 300 .ti -1c
 301 .RI "netsnmp_transport * \fBsnmp_sess_transport\fP (void *sessp)"
 302 .br
 303 .ti -1c
 304 .RI "void \fBsnmp_sess_transport_set\fP (void *sp, netsnmp_transport *t)"
 305 .br
 306 .ti -1c
 307 .RI "oid * \fBsnmp_duplicate_objid\fP (const oid *objToCopy, size_t objToCopyLen)"
 308 .br
 309 .ti -1c
 310 .RI "u_int \fBsnmp_increment_statistic\fP (int which)"
 311 .br
 312 .ti -1c
 313 .RI "u_int \fBsnmp_increment_statistic_by\fP (int which, int count)"
 314 .br
 315 .ti -1c
 316 .RI "u_int \fBsnmp_get_statistic\fP (int which)"
 317 .br
 318 .ti -1c
 319 .RI "void \fBsnmp_init_statistics\fP (void)"
 320 .br
 321 .in -1c
 322 .SS "Variables"
 323
 324 .in +1c
 325 .ti -1c
 326 .RI "session_list * \fBSessions\fP = NULL"
 327 .br
 328 .ti -1c
 329 .RI "int \fBsnmp_errno\fP = 0"
 330 .br
 331 .in -1c
 332 .SH "DEFINE DOCUMENTATION"
 333 .PP
 334 .SS "#define DEBUGPRINTPDUTYPE(token, type)"
 335 .PP
 336 \fBValue:\fP
 337 .PP
 338 .nf
 339 switch(type) { \
 340       case SNMP_MSG_GET: \
 341         DEBUGDUMPSECTION(token, 'PDU-GET'); \
 342         break; \
 343       case SNMP_MSG_GETNEXT: \
 344         DEBUGDUMPSECTION(token, 'PDU-GETNEXT'); \
 345         break; \
 346       case SNMP_MSG_RESPONSE: \
 347         DEBUGDUMPSECTION(token, 'PDU-RESPONSE'); \
 348         break; \
 349       case SNMP_MSG_SET: \
 350         DEBUGDUMPSECTION(token, 'PDU-SET'); \
 351         break; \
 352       case SNMP_MSG_GETBULK: \
 353         DEBUGDUMPSECTION(token, 'PDU-GETBULK'); \
 354         break; \
 355       case SNMP_MSG_INFORM: \
 356         DEBUGDUMPSECTION(token, 'PDU-INFORM'); \
 357         break; \
 358       case SNMP_MSG_TRAP2: \
 359         DEBUGDUMPSECTION(token, 'PDU-TRAP2'); \
 360         break; \
 361       case SNMP_MSG_REPORT: \
 362         DEBUGDUMPSECTION(token, 'PDU-REPORT'); \
 363         break; \
 364       default: \
 365         DEBUGDUMPSECTION(token, 'PDU-UNKNOWN'); \
 366         break; \
 367     }
 368 .fi
 369 .PP
 370 Definition at line 364 of file snmp_api.c.
 371 .SS "#define timercmp(tvp, uvp, cmp)"
 372 .PP
 373 \fBValue:\fP
 374 .PP
 375 .nf
 376 \
 377         ((tvp)->tv_sec cmp (uvp)->tv_sec || \
 378         ((tvp)->tv_sec == (uvp)->tv_sec && \
 379           \
 380         (tvp)->tv_usec cmp (uvp)->tv_usec))
 381 .fi
 382 .PP
 383 Definition at line 135 of file snmp_api.c.
 384 .SH "FUNCTION DOCUMENTATION"
 385 .PP
 386 .SS "int netsnmp_oid_equals (const oid * in_name1, size_t len1, const oid * in_name2, size_t len2)"
 387 .PP
 388 Compares 2 OIDs to determine if they are exactly equal.
 389 .PP
 390 This should be faster than doing a snmp_oid_compare for different length OIDs, since the length is checked first and if != returns immediately. Might be very slighly faster if lengths are ==.
 391 .PP
 392 Parameters: \fP
 393 .in +1c
 394 .TP
 395 \fB\fIin_name1\fP\fP
 396 A pointer to the first oid.
 397 .TP
 398 \fB\fIlen1\fP\fP
 399 length of the first OID (in segments, not bytes)
 400 .TP
 401 \fB\fIin_name2\fP\fP
 402 A pointer to the second oid.
 403 .TP
 404 \fB\fIlen2\fP\fP
 405 length of the second OID (in segments, not bytes)
 406 .PP
 407 \fBReturns: \fP
 408 .in +1c
 409 0 if they are equal, 1 if they are not.
 410 .PP
 411 Definition at line 6044 of file snmp_api.c.
 412 .SS "int netsnmp_oid_find_prefix (const oid * in_name1, size_t len1, const oid * in_name2, size_t len2)"
 413 .PP
 414 Given two OIDs, determine the common prefix to them both.
 415 .PP
 416 Parameters: \fP
 417 .in +1c
 418 .TP
 419 \fB\fIin_name1\fP\fP
 420 A pointer to the first oid.
 421 .TP
 422 \fB\fIlen1\fP\fP
 423 Length of the first oid.
 424 .TP
 425 \fB\fIin_name2\fP\fP
 426 A pointer to the second oid.
 427 .TP
 428 \fB\fIlen2\fP\fP
 429 Length of the second oid.
 430 .PP
 431 \fBReturns: \fP
 432 .in +1c
 433 length of largest common index of commonality. 1 = first, 0 if none * or -1 on error.
 434 .PP
 435 Definition at line 6100 of file snmp_api.c.
 436 .SS "int netsnmp_oid_is_subtree (const oid * in_name1, size_t len1, const oid * in_name2, size_t len2)"
 437 .PP
 438 Identical to netsnmp_oid_equals, except only the length up to len1 is compared.
 439 .PP
 440 Functionally, this determines if in_name2 is equal or a subtree of in_name1
 441 .PP
 442 Parameters: \fP
 443 .in +1c
 444 .TP
 445 \fB\fIin_name1\fP\fP
 446 A pointer to the first oid.
 447 .TP
 448 \fB\fIlen1\fP\fP
 449 length of the first OID (in segments, not bytes)
 450 .TP
 451 \fB\fIin_name2\fP\fP
 452 A pointer to the second oid.
 453 .TP
 454 \fB\fIlen2\fP\fP
 455 length of the second OID (in segments, not bytes)
 456 .PP
 457 \fBReturns: \fP
 458 .in +1c
 459 0 if one is a common prefix of the other.
 460 .PP
 461 Definition at line 6080 of file snmp_api.c.
 462 .SS "int snmp_oid_compare (const oid * in_name1, size_t len1, const oid * in_name2, size_t len2)"
 463 .PP
 464 lexicographical compare two object identifiers.
 465 .PP
 466 Caution: this method is called often by command responder applications (ie, agent).
 467 .PP
 468 \fBReturns: \fP
 469 .in +1c
 470 -1 if name1 < name2, 0 if name1 = name2, 1 if name1 > name2
 471 .PP
 472 Definition at line 5976 of file snmp_api.c.
 473 .SS "int snmp_oidtree_compare (const oid * in_name1, size_t len1, const oid * in_name2, size_t len2)"
 474 .PP
 475 Compares 2 OIDs to determine if they are equal up until the shortest length.
 476 .PP
 477 Parameters: \fP
 478 .in +1c
 479 .TP
 480 \fB\fIin_name1\fP\fP
 481 A pointer to the first oid.
 482 .TP
 483 \fB\fIlen1\fP\fP
 484 length of the first OID (in segments, not bytes)
 485 .TP
 486 \fB\fIin_name2\fP\fP
 487 A pointer to the second oid.
 488 .TP
 489 \fB\fIlen2\fP\fP
 490 length of the second OID (in segments, not bytes)
 491 .PP
 492 \fBReturns: \fP
 493 .in +1c
 494 0 if they are equal, 1 if in_name1 is > in_name2, or -1 if <.
 495 .PP
 496 Definition at line 6025 of file snmp_api.c.