chiark / gitweb /
option for no inotify; manpage fix
[innduct.git] / 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).