doc/man/inndcomm.3

   1 .\" $Revision: 1586 $
   2 .TH INNDCOMM 3
   3 .SH NAME
   4 inndcomm \- INND communication part of InterNetNews library
   5 .SH SYNOPSIS
   6 .nf
   7 .ta \w'    unsigned long    'u
   8 .B
   9 #include "inndcomm.h"
  10
  11 .B "int"
  12 .B "ICCopen()"
  13
  14 .B "int"
  15 .B "ICCclose()"
  16
  17 .B "void"
  18 .B "ICCsettimeout(i)"
  19 .B "    int     i;"
  20
  21 .B "int"
  22 .B "ICCcommand(cmd, argv, replyp)"
  23 .B "    char    cmd;"
  24 .B "    char    *argv[];"
  25 .B "    char    **replyp;"
  26
  27 .B "int"
  28 .B "ICCcancel(mesgid)"
  29 .B "    char    *mesgid;"
  30
  31 .B "int"
  32 .B "ICCreserve(why)"
  33 .B "    char    *why;"
  34
  35 .B "int"
  36 .B "ICCpause(why)"
  37 .B "    char    *why;"
  38
  39 .B "int"
  40 .B "ICCgo(why)"
  41 .B "    char    *why;"
  42
  43 .B "extern char *ICCfailure;"
  44 .fi
  45 .SH DESCRIPTION
  46 The routines described in this manual page are part of the InterNetNews
  47 library,
  48 .IR libinn (3).
  49 They are used to send commands to a running
  50 .IR innd (8)
  51 daemon on the local host.
  52 The letters ``ICC'' stand for
  53 .IR I nnd
  54 .IR C ontrol
  55 .IR C ommand.
  56 .PP
  57 .I ICCopen
  58 creates a
  59 Unix-domain datagram socket and binds it to the server's control socket, if
  60 .I <HAVE_UNIX_DOMAIN_SOCKETS in include/config.h>
  61 is defined.  Otherwise it creates
  62 a named pipe for communicating with the server.
  63 It returns \-1 on failure or zero on success.
  64 This routine must be called before any other routine.
  65 .PP
  66 .I ICCclose
  67 closes any descriptors that have been created by
  68 .IR ICCopen .
  69 It returns \-1 on failure or zero on success.
  70 .PP
  71 .I ICCsettimeout
  72 can be called before any of the following routines to determine how long
  73 the library should wait before giving up on getting the server's reply.
  74 This is done by setting and catching a SIGALRM
  75 .IR signal (2).
  76 If the timeout is less then zero then no reply will be waited for.
  77 The SC_SHUTDOWN, SC_XABORT, and SC_XEXEC commands do not get a reply either.
  78 The default, which can be obtained by setting the timeout to zero, is to
  79 wait until the server replies.
  80 .PP
  81 .I ICCcommand
  82 sends the command
  83 .I cmd
  84 with parameters
  85 .I argv
  86 to the server.
  87 It returns \-1 on error.
  88 If the server replies, and
  89 .I replyp
  90 is not NULL, it will be filled in with an allocated buffer that contains
  91 the full text of the server's reply.
  92 This buffer is a string in the form of ``<digits><space><text>''
  93 where ``digits'' is the text value of the recommended exit code;
  94 zero indicates success.
  95 Replies longer then 4000 bytes will be truncated.
  96 The possible values of
  97 .I cmd
  98 are defined in the ``inndcomm.h'' header file.
  99 The parameters for each command are described in
 100 .IR ctlinnd (8).
 101 This routine returns \-1 on communication failure, or the exit status
 102 sent by the server which will never be negative.
 103 .PP
 104 .I ICCcancel
 105 sends a ``cancel'' message to the server.
 106 .I Mesgid
 107 is the Message-ID of the article that should be canceled.
 108 The return value is the same as for
 109 .IR ICCcommand .
 110 .PP
 111 .IR ICCpause ,
 112 .IR ICCreserve ,
 113 and
 114 .I ICCgo
 115 send a ``pause,'' ``reserve,'' or ``go'' command to the server, respectively.
 116 If
 117 .I ICCreserve
 118 is used, then the
 119 .I why
 120 value used in the
 121 .I ICCpause
 122 invocation must match; the value used in the
 123 .I ICCgo
 124 invocation must always match that the one used in the
 125 .I ICCpause
 126 invocation.
 127 The return value for all three routines is the same as for
 128 .IR ICCcommand .
 129 .PP
 130 If any routine described above fails, the
 131 .I ICCfailure
 132 variable will identify the system call that failed.
 133 .SH HISTORY
 134 Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.
 135 .de R$
 136 This is revision \\$3, dated \\$4.
 137 ..
 138 .R$ $Id: inndcomm.3 1586 1998-12-09 15:53:55Z kondou $
 139 .SH "SEE ALSO"
 140 ctlinnd(8),
 141 innd(8),
 142 libinn(3).