doc/man/libinn.3

   1 .\" $Revision: 6124 $
   2 .TH LIBINN 3
   3 .SH NAME
   4 libinn \- InterNetNews library routines
   5 .SH SYNOPSIS
   6 .nf
   7 .ta \w'    unsigned long    'u
   8 .B
   9 #include "libinn.h"
  10
  11 .B "typedef struct _TIMEINFO {"
  12 .B "    time_t  time;"
  13 .B "    long    usec;"
  14 .B "    long    tzone;
  15 .B "} TIMEINFO;"
  16
  17 .B "char *"
  18 .B "GenerateMessageID(domain)"
  19 .B "    char    *domain;"
  20
  21 .B "void"
  22 .B "HeaderCleanFrom(from)"
  23 .B "    char    *from;"
  24
  25 .B "char *"
  26 .B "HeaderFind(Article, Header, size)"
  27 .B "    char    *Article;"
  28 .B "    char    *Header;"
  29 .B "    int     size;"
  30
  31 .B "FILE *"
  32 .B "CAopen(FromServer, ToServer)"
  33 .B "    FILE    *FromServer;"
  34 .B "    FILE    *ToServer;"
  35
  36 .B "FILE *"
  37 .B "CAlistopen(FromServer, ToServer, request)"
  38 .B "    FILE    *FromServer;"
  39 .B "    FILE    *ToServer;"
  40 .B "    char    *request;"
  41
  42 .B "void"
  43 .B "CAclose()"
  44
  45 .B "struct _DDHANDLE *"
  46 .B "DDstart(FromServer, ToServer)"
  47 .B "    FILE    *FromServer;"
  48 .B "    FILE    *ToServer;"
  49
  50 .B "void"
  51 .B "DDcheck(h, group)"
  52 .B "    DDHANDLE        *h;"
  53 .B "    char    *group;"
  54
  55 .B "char *"
  56 .B "DDend(h)"
  57 .B "    DDHANDLE        *h;"
  58
  59 .B "void"
  60 .B "close_on_exec(fd, flag)"
  61 .B "    int     fd;"
  62 .B "    bool    flag;"
  63
  64 .B "int"
  65 .B "nonblocking(fd, flag)"
  66 .B "    int     fd;"
  67 .B "    bool    flag;"
  68
  69 .B "bool"
  70 .B "inn_lock_file(fd, type, flag)"
  71 .B "    int     fd;"
  72 .B "    LOCKTYPE        type;"
  73 .B "    bool    block;"
  74
  75 .B "char *"
  76 .B "GetFQDN(domain)"
  77 .B "    char    *domain;"
  78
  79 .B "char *"
  80 .B "GetModeratorAddress(FromServer, ToServer, group, moderatormailer)"
  81 .B "    FILE    *FromServer;"
  82 .B "    FILE    *ToServer;"
  83 .B "    char    *group;"
  84 .B "    char    *moderatormailer;"
  85
  86 .B "int"
  87 .B "GetResourceUsage(usertime, systime)"
  88 .B "    double  *usertime;"
  89 .B "    double  *systime;"
  90
  91 .B "int"
  92 .B "GetTimeInfo(now)"
  93 .B "    TIMEINFO        *now;"
  94
  95 .B "int"
  96 .B "NNTPlocalopen(FromServerp, ToServerp, errbuff)"
  97 .B "    FILE    **FromServerp;"
  98 .B "    FILE    **ToServerp;"
  99 .B "    char    *errbuff;"
 100
 101 .B "int"
 102 .B "NNTPremoteopen(port, FromServerp, ToServerp, errbuff)"
 103 .B "    int     port;"
 104 .B "    FILE    **FromServerp;"
 105 .B "    FILE    **ToServerp;"
 106 .B "    char    *errbuff;"
 107
 108 .B "int"
 109 .B "NNTPconnect(host, port, FromServerp, ToServerp, errbuff)"
 110 .B "    char    *host;"
 111 .B "    int     port;"
 112 .B "    FILE    **FromServerp;"
 113 .B "    FILE    **ToServerp;"
 114 .B "    char    *errbuff;"
 115
 116 .B "int"
 117 .B "NNTPsendarticle(text, ToServer, Terminate)"
 118 .B "    char    *text;"
 119 .B "    FILE    *ToServer;"
 120 .B "    int     Terminate;"
 121
 122 .B "int"
 123 .B "NNTPsendpassword(server, FromServer, ToServer)"
 124 .B "    char    *server;"
 125 .B "    FILE    *FromServer;"
 126 .B "    FILE    *ToServer;"
 127
 128 .B "void"
 129 .B "Radix32(value, p)
 130 .B "    unsigned long   value;"
 131 .B "    char    *p;"
 132
 133 .B "char *"
 134 .B "ReadInFile(name, Sbp)"
 135 .B "    char    *name;"
 136 .B "    struct stat     *Sbp;"
 137
 138 .B "char *"
 139 .B "ReadInDescriptor(fd, Sbp)"
 140 .B "    int     fd;"
 141 .B "    struct stat     *Sbp;"
 142
 143 .B "HASH"
 144 .B "HashMessageID(MessageID)"
 145 .B "    const char *MessageID;"
 146 .fi
 147 .SH DESCRIPTION
 148 .I Libinn
 149 is a library of utility routines for manipulating Usenet articles and
 150 related data.
 151 It is not necessary to use the header file
 152 .IR libinn.h ;
 153 if it is not available, it is only necessary to properly declare the
 154 .I TIMEINFO
 155 datatype, as given above.
 156 .PP
 157 .I GenerateMessageID
 158 uses the current time, process-ID, and fully-qualified domain name, which is
 159 passed as an argument and used if local host can not be resolved or it is
 160 different from ``domain'' set in
 161 .IR inn.conf ,
 162 to create a Message-ID header that is highly likely to be unique.
 163 The returned value points to static space that is reused on subsequent calls.
 164 .PP
 165 .I HeaderCleanFrom
 166 removes the extraneous information from the value of a ``From'' or ``Reply-To''
 167 header and leaves just the official mailing address.
 168 In particular, the following transformations are made to the
 169 .I from
 170 parameter:
 171 .RS
 172 .nf
 173 .ta \w'stuff <address>  'u
 174 address -->  address
 175 address (stuff) -->  address
 176 stuff <address> -->  address
 177 .fi
 178 .RE
 179 The transformations are simple, based on RFC\ 1036 which limits the format
 180 of the header.
 181 .PP
 182 .I HeaderFind
 183 searches through
 184 .I Article
 185 looking for the specified
 186 .IR Header .
 187 .I Size
 188 should be the length of the header name.
 189 It returns a pointer to the value of the header, skipping leading whitespace,
 190 or NULL if the header cannot be found.
 191 .I Article
 192 should be a standard C string containing the text of the article; the end
 193 of the headers is indicated by a blank line \(em two consecutive \en
 194 characters.
 195 .PP
 196 .I CAopen
 197 and
 198 .I CAclose
 199 provide news clients with access to the active file; the ``CA'' stands for
 200 .IR C lient
 201 .IR A ctive.
 202 .I CAopen
 203 opens the
 204 .I active
 205 file for reading.
 206 It returns a pointer to an open FILE, or NULL on error.
 207 If a local or NFS-mounted copy exists,
 208 .I CAopen
 209 will use that file.
 210 The
 211 .I FromServer
 212 and
 213 .I ToServer
 214 parameters should be FILE's connected to the NNTP server for input and
 215 output, respectively.
 216 See
 217 .I NNTPremoteopen
 218 or
 219 .IR NNTPlocalopen ,
 220 below.
 221 If either parameter is NULL, then
 222 .I CAopen
 223 will just return NULL if the file is not locally available.
 224 If they are not NULL,
 225 .I CAopen
 226 will use them to query the NNTP server using
 227 the ``list'' command to make a local temporary copy.
 228 .PP
 229 The
 230 .I CAlistopen
 231 sends a ``list'' command to the server and returns a temporary file
 232 containing the results.
 233 The
 234 .I request
 235 parameter, if not NULL, will be sent as an argument to the command.
 236 Unlike
 237 .IR CAopen ,
 238 this routine will never use a locally-available copy of the active file.
 239 .PP
 240 .I CAclose
 241 closes the active file and removes any temporary file that might have
 242 been created by
 243 .I CAopen
 244 or
 245 .IR CAlistopen .
 246 .PP
 247 .I CloseOnExec
 248 can make a descriptor ``close-on-exec'' so that it is not shared
 249 with any child processes.
 250 If the flag is non-zero, the file is so marked; if zero, the ``close-on-exec''
 251 mode is cleared.
 252 .PP
 253 .IR DDstart ,
 254 .IR DDcheck ,
 255 and
 256 .I DDend
 257 are used to set the Distribution header; the ``DD'' stands for
 258 .IR D efault
 259 .IR D istribution.
 260 The
 261 .I distrib.pats
 262 file is consulted to determine the proper value for the Distribution
 263 header after all newsgroups have been checked.
 264 .I DDstart
 265 begins the parsing.
 266 It returns a pointer to an opaque handle that should be used on subsequent
 267 calls.
 268 The
 269 .I FromServer
 270 and
 271 .I ToServer
 272 parameters should be FILE's connected to the NNTP server for input and
 273 output, respectively.
 274 If either parameter is NULL, then an empty default will ultimately be returned
 275 if the file is not locally available.
 276 .PP
 277 .I DDcheck
 278 should be called
 279 with the handle,
 280 .IR h ,
 281 returned by
 282 .I DDstart
 283 and a newgroups,
 284 .IR group ,
 285 to check.
 286 It can be called as often as necessary.
 287 .PP
 288 .I DDend
 289 releases any state maintained in the handle and returns an allocated copy
 290 of the text that should be used for the Distribution header.
 291 .PP
 292 .I SetNonBlocking
 293 enables (if
 294 .I flag
 295 is non-zero) or disables (if
 296 .I flag
 297 is zero) non-blocking I/O on the indicated descriptor.
 298 It returns \-1 on failure or zero on success.
 299 .PP
 300 .I inn_lock_file
 301 tries to lock the file descriptor
 302 .IR fd .
 303 If
 304 .I block
 305 is true it will block until the lock can be made, otherwise
 306 it will return false if the file cannot be locked.
 307 .I type
 308 is one of: INN_LOCK_READ, INN_LOCK_WRITE, or INN_LOCK_UNLOCK.
 309 It returns false on failure or true on success.
 310 .PP
 311 .I GetFQDN
 312 returns the fully-qualified domain name of the local host.
 313 .I Domain
 314 is used if local host can not be resolved.
 315 The returned value points to static space that is reused on subsequent calls,
 316 or NULL on error.
 317 .PP
 318 .I GetModeratorAddress
 319 returns the mailing address of the moderator for specified
 320 .I group
 321 or NULL on error.
 322 .I Moderatormailer
 323 is used as its address, if there is no matched moderator.
 324 See
 325 .IR moderators (5)
 326 for details on how the address is determined.
 327 .I GetModeratorAddress
 328 does no checking to see if the specified group is actually moderated.
 329 The returned value points to static space that is reused on subsequent
 330 calls.
 331 The
 332 .I FromServer
 333 and
 334 .I ToServer
 335 parameters should be FILE's connected to the NNTP server for input and
 336 output, respectively.  If either of these parameters is NULL, then an
 337 attempt to get the list from a local copy is made.
 338 .PP
 339 .I GetResourceUsage
 340 fills in the
 341 .I usertime
 342 and
 343 .I systime
 344 parameters with the total user and system time used by the current
 345 process and any children it may have spawned.
 346 If
 347 .I <HAVE_GETRUSAGE in include/config.h>
 348 is defined, it gets the values by doing a
 349 .IR getrusage (2)
 350 system call; otherwise it calls
 351 .IR times (2).
 352 It returns \-1 on failure, or zero on success.
 353 .PP
 354 .I GetTimeInfo
 355 fills in the
 356 .I now
 357 parameter with information about the current time and tzone.
 358 The ``time'' and ``usec'' fields will be filled in by a call to
 359 .IR gettimeofday (2)
 360 if
 361 .I <$ac_cv_func_gettimeofday in config.cache>
 362 is ``yes''.  Otherwise, the ``time'' field will be filled in by a call to
 363 .IR time (2),
 364 and the ``usec'' field will be set to zero.
 365 The ``tzone'' field will be filled in with the current offset from GMT.
 366 If
 367 .I <HAVE_TM_GMTOFF in include/config.h>
 368 is defined, this is done by calling
 369 .IR localtime (3)
 370 and taking the value of the ``tm_gmtoff'' field, negating it, and dividing
 371 it by 60.
 372 Otherwise, this is done by calling
 373 .IR localtime (3)
 374 and comparing the value with that returned by a call to
 375 .IR gmtime (3).
 376
 377 For efficiency, the ``tzone'' field is only recalculated if more than an
 378 hour pass passed since the last time
 379 .I GetTimeInfo
 380 has been called.
 381 This routine returns \-1 on failure, or zero on success.
 382 .PP
 383 .I NNTPlocalopen
 384 opens a connection to the private port of an InterNetNews server running on
 385 the local host, if
 386 .I <HAVE_UNIX_DOMAIN_SOCKETS in include/config.h>
 387 is defined.
 388 It returns \-1 on failure, or zero on success.
 389 .I FromServerp
 390 and
 391 .I ToServerp
 392 will be filled in with FILE's which can be used to communicate
 393 with the server.
 394 .I Errbuff
 395 can either be NULL or a pointer to a buffer at least 512 bytes long.
 396 If not NULL, and the server refuses the connection, then it will be
 397 filled in with the text of the server's reply.
 398 This routine is not for general use.
 399 If
 400 .I <HAVE_UNIX_DOMAIN_SOCKETS in include/config.h>
 401 is not defined, this
 402 is a stub routine, for compatibility with systems that have Unix-domain
 403 stream sockets.
 404 It always returns \-1.
 405 .PP
 406 .I NNTPremoteopen
 407 does the same except that it uses ``innconf->server''
 408 as the local server, and opens a connection to the
 409 .IR port .
 410 Any client program can use this routine.
 411 It returns \-1 on failure, or zero on success.
 412 .PP
 413 .I NNTPconnect
 414 is the same as
 415 .I NNTPremoteopen
 416 except that the desired host is given as the
 417 .I host
 418 parameter.
 419 .PP
 420 .I NNTPsendarticle
 421 writes
 422 .I text
 423 on
 424 .I ToServer
 425 using NNTP conventions for line termination.
 426 The text should consist of one or more lines ending with a newline.
 427 If
 428 .I Terminate
 429 is non-zero, then the routine will also write the NNTP data-termination
 430 marker on the stream.
 431 It returns \-1 on failure, or zero on success.
 432 .PP
 433 .I NNTPsendpassword
 434 sends authentication information to an NNTP server by finding the appropriate
 435 entry in the
 436 .I passwd.nntp
 437 file.
 438 .I Server
 439 contains the name of the host; ``innconf->server'' will be used if
 440 .I server
 441 is NULL.
 442 .I FromServer
 443 and
 444 .I ToServer
 445 should be FILE's that are connected to the server.
 446 No action is taken if the specified host is not listed in the password file.
 447 .PP
 448 .I Radix32
 449 converts the number in
 450 .I value
 451 into a radix-32 string into the buffer pointed to by
 452 .IR p .
 453 The number is split into five-bit pieces and each pieces is converted
 454 into a character using the alphabet
 455 .I "0..9a..v"
 456 to represent the numbers 0..32.
 457 Only the lowest 32 bits of
 458 .I value
 459 are used, so
 460 .I p
 461 need only point to a buffer of eight bytes (seven characters and the
 462 trailing \e0).
 463 .PP
 464 .I ReadInFile
 465 reads the file named
 466 .I name
 467 into allocated memory, appending a terminating \e0 byte.
 468 It returns a pointer to the space, or NULL on error.
 469 If
 470 .I Sbp
 471 is not NULL, it is taken as the address of a place to store the results
 472 of a
 473 .IR stat (2)
 474 call.
 475 .PP
 476 .I ReadInDescriptor
 477 performs the same function as
 478 .I ReadInFile
 479 except that
 480 .I fd
 481 refers to an already-open file.
 482 .PP
 483 .I HashMessageID
 484 returns hashed message-id using MD5.
 485 .SH EXAMPLES
 486 .RS
 487 .nf
 488 char    *p;
 489 char    *Article;
 490 char    buff[256], errbuff[256];
 491 FILE    *F;
 492 FILE    *ToServer;
 493 FILE    *FromServer;
 494 int     port = 119;
 495
 496 if ((p = HeaderFind(Article, "From", 4)) == NULL)
 497     Fatal("Can't find From line");
 498 (void)strcpy(buff, p);
 499 HeaderCleanFrom(buff);
 500
 501 if ((F = CAopen(FromServer, ToServer)) == NULL)
 502     Fatal("Can't open active file");
 503
 504 /* Don't pass the file on to our children. */
 505 CloseOnExec(fileno(F), 1);
 506
 507 /* Make a local copy. */
 508 p = ReadInDescriptor(fileno(F), (struct stat *)NULL);
 509
 510 /* Close the file. */
 511 CAclose();
 512
 513 if (NNTPremoteopen(port, &FromServer, &ToServer, errbuff) < 0)
 514     Fatal("Can't connect to server");
 515
 516 if ((p = GetModeratorAddress("comp.sources.unix")) == NULL)
 517     Fatal("Can't find moderator's address");
 518 .fi
 519 .RE
 520 .SH HISTORY
 521 Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.
 522 .de R$
 523 This is revision \\$3, dated \\$4.
 524 ..
 525 .R$ $Id: libinn.3 6124 2003-01-14 06:03:29Z rra $
 526 .SH "SEE ALSO"
 527 active(5),
 528 dbz(3z),
 529 parsedate(3),
 530 inn.conf(5),
 531 inndcomm(3),
 532 moderators(5),
 533 passwd.nntp(5).