1 SESSION LAYER PROTOCOL FOR CITADEL/UX
2 (c) 1995-2000 by Art Cancro et. al. All Rights Reserved
8 This is an attempt to document the session layer protocol used by the
9 Citadel/UX system, beginning with version 4.00, which is the first version
10 to implement a client/server paradigm. It is intended as a resource for
11 programmers who intend to develop their own Citadel clients, but it may have
15 IMPORTANT NOTE TO DEVELOPERS!
16 -----------------------------
18 Anyone who wants to add commands or other functionality to this protocol,
19 *please* get in touch so that these efforts can be coordinated. New
20 commands added by other developers can be added to this document, so we
21 don't end up with new server commands from multiple developers which have
22 the same name but perform different functions. If you don't coordinate new
23 developments ahead of time, please at least send in an e-mail documenting
24 what you did, so that your new commands can be added to this document.
26 The coordinator of the Citadel/UX project is Art Cancro
27 <ajc@uncnsrd.mt-kisco.ny.us>.
30 CONNECTING TO A SERVER
31 ----------------------
33 The protocols used below the session layer are beyond the scope of this
34 document, but we will briefly cover the methodology employed by Citadel/UX.
36 Citadel/UX offers Citadel BBS service using TCP/IP. It does so via a
37 multithreaded server listening on a TCP port. Older (4.xx) versions employed
38 an inetd-based server.
40 The port number officially assigned to Citadel by the IANA is TCP/504. Since
41 our session layer assumes a clean, reliable, sequenced connection, the use
42 of UDP would render the server unstable and unusable, so we stick with TCP.
45 GENERAL INFORMATION ABOUT THE SERVER
46 ------------------------------------
48 The server is connection-oriented and stateful: each client requires its own
49 connection to a server process, and when a command is sent, the client must
50 read the response, and then transfer data or change modes if necessary.
52 The session layer is very much like other Internet protocols such as SMTP
53 or NNTP. A client program sends one-line commands to the server, and the
54 server responds with a three-digit numeric result code followed by a message
55 describing what happened. This cycle continues until the end of the
58 Unlike protocols such as FTP, all data transfers occur in-band. This means
59 that the same connection that is used for exchange of client/server
60 messages, will also be used to transfer data back and forth. (FTP opens a
61 separate connection for data transfers.) We do this to allow the server to
62 function over transports which can only handle one session at a time (such
63 as a dialup connection).
69 The server will respond to all commands with a 3-digit result code, which
70 will be the first three characters on the line. The rest of the line may
71 contain a human-readable string explaining what happened. (Some client
72 software will display some of these strings to the user.)
74 The first digit is the most important. The following codes are defined for
75 this position: ERROR, OK, MORE_DATA, LISTING_FOLLOWS, and SEND_LISTING.
77 The second and third digits may provide a reason as to why a command
78 succeeded or failed. See ipcdef.h for the available codes.
80 ERROR means the command did not complete.
81 OK means the command executed successfully.
82 MORE_DATA means the command executed partially. Usually this means that
83 another command needs to be executed to complete the operation. For example,
84 sending the USER command to log in a user usually results in a MORE_DATA
85 result code, because the client needs to execute a PASS command to send the
86 password and complete the login.
87 LISTING_FOLLOWS means that after the server response, the server will
88 output a listing of some sort. The client *must* read the listing, whether
89 it wants to or not. The end of the listing is signified by the string
90 "000" on a line by itself.
91 SEND_LISTING is the opposite of LISTING_FOLLOWS. It means that the client
92 should begin sending a listing of some sort. The client *must* send something,
93 even if it is an empty listing. Again, the listing ends with "000" on a line
100 Zero or more parameters may be passed to a command. When more than one
101 parameter is passed to a command, they should be separated by the "|"
104 In this example, we're using the "SETU" command and passing three
105 parameters: 80, 24, and 260.
107 When the server spits out data that has parameters, if more than one
108 parameter is returned, they will be separated by the "|" symbol like
111 In this example, we just executed the "GETU" command, and it returned us
112 an OK result code (the '2' in the 200) and three parameters: 80, 24, and
119 This is a listing of all the commands that a Citadel/UX server can execute.
124 This command does nothing. It takes no arguments and always returns
125 OK. It is intended primarily for testing and development, but it might also
126 be used as a "keep alive" command to prevent the server from timing out, if
127 it's running over a transport that needs this type of thing.
130 ECHO (ECHO something)
132 This command also does nothing. It simply returns OK followed by whatever
138 Terminate the server connection. This command takes no arguments. It
139 returns OK and closes the connection immediately.
144 Log out the user without closing the server connection. It always returns
145 OK even if no user is logged in.
148 USER (send USER name)
150 The first step in logging in a user. This command takes one argument: the
151 name of the user to be logged in. If the user exists, a MORE_DATA return
152 code will be sent, which means the client should execute PASS as the next
153 command. If the user does not exist, ERROR is returned.
158 The second step in logging in a user. This command takes one argument: the
159 password for the user we are attempting to log in. If the password doesn't
160 match the correct password for the user we specified for the USER command,
161 or if a USER command has not been executed yet, ERROR is returned. If the
162 password is correct, OK is returned and the user is now logged in... and
163 most of the other server commands can now be executed. Along with OK, the
164 following parameters are returned:
166 0 - The user's name (in case the client wants the right upper/lower casing)
167 1 - The user's current access level
170 4 - Various flags (see citadel.h)
174 NEWU (create NEW User account)
176 This command creates a new user account and logs it in. The argument to
177 this command will be the name of the account. No case conversion is done
178 on the name. Note that the new account is installed with a default
179 configuration, and no password, so the client should immediately prompt the
180 user for a password and install it with the SETP command as soon as this
181 command completes. This command returns OK if the account was created and
182 logged in, or ERROR if another user already exists with this name. If OK,
183 it will also return the same parameters that PASS returns.
186 SETP (SET new Password)
188 This command sets a new password for the currently logged in user. The
189 argument to this command will be the new password. The command always
190 returns OK, unless the client is not logged in, in which case it will return
194 LKRN (List Known Rooms with New messages)
196 List known rooms with new messages. If the client is not logged in, ERROR
197 is returned. Otherwise, LISTING_FOLLOWS is returned, followed by the room
198 listing. Each line in the listing contains the full name of a room, followed
199 by the '|' symbol, and then a number that may contain the following bits:
202 #define QR_PERMANENT 1 /* Room does not purge */
203 #define QR_PRIVATE 4 /* Set for any type of private room */
204 #define QR_PASSWORDED 8 /* Set if there's a password too */
205 #define QR_GUESSNAME 16 /* Set if it's a guessname room */
206 #define QR_DIRECTORY 32 /* Directory room */
207 #define QR_UPLOAD 64 /* Allowed to upload */
208 #define QR_DOWNLOAD 128 /* Allowed to download */
209 #define QR_VISDIR 256 /* Visible directory */
210 #define QR_ANONONLY 512 /* Anonymous-Only room */
211 #define QR_ANON2 1024 /* Anonymous-Option room */
212 #define QR_NETWORK 2048 /* Shared network room */
213 #define QR_PREFONLY 4096 /* Preferred status needed to enter */
214 #define QR_READONLY 8192 /* Aide status required to post */
217 Other bits may be defined in the future. The listing terminates, as with
218 all listings, with "000" on a line by itself.
220 Starting with version 4.01 and above, floors are supported. The first
221 argument to LKRN should be the number of the floor to list rooms from. Only
222 rooms from this floor will be listed. If no arguments are passed to LKRN, or
223 if the floor number requested is (-1), rooms on all floors will be listed.
225 The third field displayed on each line is the number of the floor the room
226 is on. The LFLR command should be used to associate floor numbers with
229 The fourth field displayed on each line is a "room listing order." Unless
230 there is a compelling reason not to, clients should sort any received room
231 listings by this value.
235 LKRO (List Known Rooms with Old [no new] messages)
237 This follows the same usage and format as LKRN.
240 LZRM (List Zapped RooMs)
242 This follows the same usage and format as LKRN and LKRO.
245 LKRA (List All Known Rooms)
247 Same format. Lists all known rooms, with or without new messages.
250 LRMS (List all accessible RooMS)
252 Again, same format. This command lists all accessible rooms, known and
253 forgotten, with and without new messages. It does not, however, list
254 inaccessible private rooms.
257 GETU (GET User configuration)
259 This command retrieves the screen dimensions and user options for the
260 currently logged in account. ERROR will be returned if no user is logged
261 in, of course. Otherwise, OK will be returned, followed by four parameters.
262 The first parameter is the user's screen width, the second parameter is the
263 user's screen height, and the third parameter is a bag of bits with the
266 #define US_LASTOLD 16 /* Print last old message with new */
267 #define US_EXPERT 32 /* Experienced user */
268 #define US_UNLISTED 64 /* Unlisted userlog entry */
269 #define US_NOPROMPT 128 /* Don't prompt after each message */
270 #define US_DISAPPEAR 512 /* Use "disappearing msg prompts" */
271 #define US_PAGINATOR 2048 /* Pause after each screen of text */
273 There are other bits, too, but they can't be changed by the user (see below).
275 The fourth parameter, if present, is the moderation level this user is
279 SETU (SET User configuration)
281 This command does the opposite of SETU: it takes the screen dimensions and
282 user options (which were probably obtained with a GETU command, and perhaps
283 modified by the user) and writes them to the user account. This command
284 should be passed four parameters: the screen width, the screen height,
285 the option bits (see above), and the desired moderation level to filter at.
287 Note that there exist bits here which are not listed in this document. Some
288 are flags that can only be set by Aides or the system administrator. SETU
289 will ignore attempts to toggle these bits. There also may be more user
290 settable bits added at a later date. To maintain later downward compatibility,
291 the following procedure is suggested:
293 1. Execute GETU to read the current flags
294 2. Toggle the bits that we know we can toggle
295 3. Execute SETU to write the flags
297 If we are passed a bit whose meaning we don't know, it's best to leave it
298 alone, and pass it right back to the server. That way we can use an old
299 client on a server that uses an unknown bit without accidentally clearing
300 it every time we set the user's configuration.
305 This command is used to goto a new room. When the user first logs in (login
306 is completed after execution of the PASS command) this command is
307 automatically and silently executed to take the user to the first room in the
308 system (usually called the Lobby).
310 This command can be passed one or two parameters. The first parameter is,
311 of course, the name of the room. Although it is not case sensitive, the
312 full name of the room must be used. Wildcard matching or unique string
313 matching of room names should be the responsibility of the client.
315 Note that the reserved room name "_BASEROOM_" can be passed to the server
316 to cause the goto command to take the user to the first room in the system,
317 traditionally known as the Lobby>. As long as a user is logged in, a
318 GOTO command to _BASEROOM_ is guaranteed to succeed. This is useful to
319 allow client software to return to the base room when it doesn't know
322 There are also two additional reserved room names:
323 "_MAIL_" translates to the system's designated room for e-mail messages.
324 "_BITBUCKET_" goes to whatever room has been chosen for messages
327 The second (and optional) parameter is a password, if one is required for
328 access to the room. This allows for all types of rooms to be accessed via
329 this command: for public rooms, invitation-only rooms to which the user
330 has access, and preferred users only rooms to which the user has access, the
331 room will appear in a room listing. For guess-name rooms, this command
332 will work transparently, adding the room to the user's known room list when
333 it completes. For passworded rooms, access will be denied if the password
334 is not supplied or is incorrect, or the command will complete successfully
335 if the password is correct.
337 The possible result codes are:
339 OK - The command completed successfully. User is now in the room.
340 (See the list of returned parameters below)
342 ERROR - The command did not complete successfully. Check the second and
343 third positions of the result code to find out what happened:
345 NOT_LOGGED_IN - Of course you can't go there. You didn't log in.
346 PASSWORD_REQUIRED - Either a password was not supplied, or the supplied
347 password was incorrect.
348 NO_SUCH_ROOM - The requested room does not exist.
350 The typical procedure for entering a passworded room would be:
352 1. Execute a GOTO command without supplying any password.
353 2. ERROR+PASSWORD_REQUIRED will be returned. The client now knows that
354 the room is passworded, and prompts the user for a password.
355 3. Execute a GOTO command, supplying both the room name and the password.
356 4. If OK is returned, the command is complete. If, however,
357 ERROR+PASSWORD_REQUIRED is still returned, tell the user that the supplied
358 password was incorrect. The user remains in the room he/she was previously
361 When the command succeeds, these parameters are returned:
362 0. The name of the room
363 1. Number of unread messages in this room
364 2. Total number of messages in this room
365 3. Info flag: set to nonzero if the user needs to read this room's info
366 file (see RINF command below)
367 4. Various flags associated with this room. (See LKRN cmd above)
368 5. The highest message number present in this room
369 6. The highest message number the user has read in this room
370 7. Boolean flag: 1 if this is a Mail> room, 0 otherwise.
371 8. Aide flag: 1 if the user is either the Room Aide for this room, *or* is
372 a regular Aide (this makes access checks easy).
373 9. The number of new Mail messages the user has (useful for alerting the
374 user to the arrival of new mail during a session)
375 10. The floor number this room resides on
378 MSGS (get pointers to MeSsaGeS in this room)
380 This command obtains a listing of all the messages in the current room
381 which the client may request. This command may be passed a single parameter:
382 either "all", "old", or "new" to request all messages, only old messages, or
383 new messages. Or it may be passed two parameters: "last" plus a number, in
384 which case that many message pointers will be returned, or "first" plus a
385 number, for the corresponding effect. If no parameters are specified, "all"
388 In Citadel/UX 5.00 and above, the client may also specify "gt" plus a number,
389 to list all messages in the current room with a message number greater than
392 The third argument, valid only in Citadel/UX 5.60 and above, may be either
393 0 or 1. If it is 1, this command behaves differently: before a listing is
394 returned, the client must transmit a list of fields to search for. The field
395 headers are listed below in the writeup for the "MSG0" command.
397 This command can return three possible results. An ERROR code may be returned
398 if no user is currently logged in or if something else went wrong. Otherwise,
399 LISTING_FOLLOWS will be returned, and the listing will consist of zero or
400 more message numbers, one per line. The listing ends, as always, with the
401 string "000" alone on a line by itself. The listed message numbers can be used
402 to request messages from the system. If "search mode" is being used, the
403 server will return START_CHAT_MODE, and the client is expected to transmit
404 the search criteria, and then read the message list.
406 Since this is somewhat complex, here are some examples:
408 Example 1: Read all new messages
411 Server: 100 Message list...
417 Example 2: Read the last five messages
420 Server: 100 Message list...
428 Example 3: Read all messages written by "IGnatius T Foobar"
431 Server: 800 Send template then receive message list
432 Client: from|IGnatius T Foobar
446 Note that in "search mode" the client may specify any number of search
447 criteria. These criteria are applied with an AND logic.
451 MSG0 (read MeSsaGe, mode 0)
453 This is a command used to read the text of a message. "Mode 0" implies that
454 other MSG commands (MSG1, MSG2, etc.) will probably be added later on to read
455 messages in more robust formats. This command should be passed two arguments.
456 The first is the message number of the message being requested. In server
457 version 4.04 and above, the second argument may be set to either 0 to read the
458 entire message, or 1 to read the headers only.
460 The server should, of course, make sure that the client actually has access
461 to the message being requested before honoring this request. Citadel/UX does
462 so by checking the message number against the contents of the current room. If
463 it's not there, the request is denied.
465 If the request is denied, an ERROR code will be returned. Otherwise, the
466 LISTING_FOLLOWS code will be returned, followed by the contents of the message.
467 The following fields may be sent:
469 type= Formatting type. The currently defined types are:
470 0 = "traditional" Citadel formatting. This means that newlines should be
471 treated as spaces UNLESS the first character on the next line is a space. In
472 other words, only indented lines should generate a newline on the user's screen
473 when the message is being displayed. This allows a message to be formatted to
474 the reader's screen width. It also allows the use of proportional fonts.
475 1 = a simple fixed-format message. The message should be displayed to
476 the user's screen as is, preferably in a fixed-width font that will fit 80
478 4 = MIME format message. The message text is expected to contain a header
479 with the "Content-type:" directive (and possibly others).
481 msgn= The message ID of this message on the system it originated on.
482 path= An e-mailable path back to the user who wrote the message.
484 time= The date and time of the message, in Unix format (the number of
485 seconds since midnight on January 1, 1970, GMT).
487 from= The name of the author of the message.
488 rcpt= If the message is a private e-mail, this is the recipient.
489 room= The name of the room the message originated in.
490 node= The short node name of the system this message originated on.
491 hnod= The long node name of the system this message originated on.
492 zaps= The id/node of a message which this one zaps (supersedes).
494 text Note that there is no "=" after the word "text". This string
495 signifies that the message text begins on the next line.
498 WHOK (WHO Knows room)
500 This command is available only to Aides. ERROR+HIGHER_ACCESS_REQUIRED will
501 be returned if the user is not an Aide. Otherwise, it returns
502 LISTING_FOLLOWS and then lists, one user per line, every user who has
503 access to the current room.
506 INFO (get server INFO)
508 This command will *always* return LISTING_FOLLOWS and then print out a
509 listing of zero or more strings. Client software should be written to expect
510 anywhere from a null listing to an infinite number of lines, to allow later
511 backward compatibility. The current implementation defines the following
512 parts of the listing:
514 Line 1 - Your unique session ID on the server
515 Line 2 - The node name of the server BBS
516 Line 3 - Human-readable node name of the server BBS
517 Line 4 - The fully-qualified domain name (FQDN) of the server
518 Line 5 - The name of the server software, i.e. "Citadel/UX 4.00"
519 Line 6 - (The revision level of the server code) * 100
520 Line 7 - The geographical location of the BBS (city and state if in the US)
521 Line 8 - The name of the system administrator
522 Line 9 - A number identifying the server type (see below)
523 Line 10 - The text of the system's paginator prompt
524 Line 11 - Floor Flag. 1 if the system supports floors, 0 otherwise.
525 Line 12 - Paging level. 0 if the system only supports inline paging,
526 1 if the system supports "extended" paging (check-only and
527 multiline modes). See the SEXP command for further information.
529 *** NOTE! *** The "server type" code is intended to promote global
530 compatibility in a scenario in which developers have added proprietary
531 features to their servers or clients. We are attempting to avoid a future
532 situation in which users need to keep different client software around for
533 each BBS they use. *Please*, if you are a developer and plan to add
534 proprietary features:
536 -> Your client programs should still be able to utilize servers other than
538 -> Clients other than your own should still be able to utilize your server,
539 even if your proprietary extensions aren't supported.
540 -> Please contact Art Cancro <ajc@uncnsrd.mt-kisco.ny.us> and obtain a unique
541 server type code, which can be assigned to your server program.
542 -> If you document what you did in detail, perhaps it can be added to a
543 future release of the Citadel/UX program, so everyone can enjoy it. Better
544 yet, just work with the Citadel development team on the main source tree.
546 If everyone follows this scheme, we can avoid a chaotic situation with lots
547 of confusion about which client program works with which server, etc. Client
548 software can simply check the server type (and perhaps the revision level)
549 to determine ahead of time what commands may be utilized.
551 Please refer to "developers.txt" for information on what codes belong to whom.
555 RDIR (Read room DIRectory)
557 Use this command to read the directory of a directory room. ERROR+NOT_HERE
558 will be returned if the room has no directory, or some other error; ERROR +
559 HIGHER_ACCESS_REQUIRED will be returned if the room's directory is not
560 visible and the user does not have Aide or Room Aide privileges; otherwise
561 LISTING_FOLLOWS will be returned, followed by the room's directory. Each
562 line of the directory listing will contain three fields: a filename, the
563 length of the file, and a description.
565 The server message contained on the same line with LISTING_FOLLOWS will
566 contain the name of the system and the name of the directory, such as:
567 uncnsrd.mt-kisco.ny.us|/usr/bbs/files/my_room_directory
570 SLRP (Set Last-message-Read Pointer)
572 This command is used to mark messages as having been read. Its sole parameter
573 is the number of the last message that has been read. This allows the pointer
574 to be set at any arbitrary point in the room. Optionally, the parameter
575 "highest" may be used instead of a message number, to set the pointer to the
576 number of the highest message in the room, effectively marking all messages
577 in the room as having been read (ala the Citadel <G>oto command).
579 The command will return OK if the pointer was set, or ERROR if something
580 went wrong. If OK is returned, it will be followed by a single argument
581 containing the message number the last-read-pointer was set to.
584 INVT (INViTe a user to a room)
586 This command may only be executed by Aides, or by the room aide for the
587 current room. It is used primarily to add users to invitation-only rooms,
588 but it may also be used in other types of private rooms as well. Its sole
589 parameter is the name of the user to invite.
591 The command will return OK if the operation succeeded, or ERROR if it did
592 not. ERROR+HIGHER_ACCESS_REQUIRED may also be returned if the operation
593 would have been possible if the user had higher access, and ERROR+NOT_HERE
594 may be returned if the room is not a private room.
597 KICK (KICK a user out of a room)
599 This is the opposite of INVT: it is used to kick a user out of a private
600 room. It can also be used to kick a user out of a public room, but the
601 effect will only be the same as if the user <Z>apped the room - a non-stupid
602 user can simply un-zap the room to get back in.
605 GETR (GET Room attributes)
607 This command is used for editing the various attributes associated with a
608 room. A typical "edit room" command would work like this:
609 1. Use the GETR command to get the current attributes
610 2. Change some of them around
611 3. Use SETR (see below) to save the changes
612 4. Possibly also change the room aide using the GETA and SETA commands
614 GETR takes no arguments. It will only return OK if the SETR command will
615 also return OK. This allows client software to tell the user that he/she
616 can't edit the room *before* going through the trouble of actually doing the
617 editing. Possible return codes are:
619 ERROR+NOT_LOGGED_IN - No user is logged in.
620 ERROR+HIGHER_ACCESS_REQUIRED - Not enough access. Typically, only aides
621 and the room aide associated with the current room, can access this command.
622 ERROR+NOT_HERE - Lobby>, Mail>, and Aide> cannot be edited.
623 OK - Command succeeded. Parameters are returned.
625 If OK is returned, the following parameters will be returned as well:
627 0. The name of the room
628 1. The room's password (if it's a passworded room)
629 2. The name of the room's directory (if it's a directory room)
630 3. Various flags (bits) associated with the room (see LKRN cmd above)
631 4. The floor number on which the room resides
632 5. The room listing order
635 SETR (SET Room attributes)
637 This command sets various attributes associated with the current room. It
638 should be passed the following arguments:
640 0. The name of the room
641 1. The room's password (if it's a passworded room)
642 2. The name of the room's directory (if it's a directory room)
643 3. Various flags (bits) associated with the room (see LKRN cmd above)
644 4. "Bump" flag (see below)
645 5. The floor number on which the room should reside
646 6. The room listing order
648 *Important: You should always use GETR to retrieve the current attributes of
649 the room, then change what you want to change, and then use SETR to write it
650 all back. This is particularly important with respect to the flags: if a
651 particular bit is set, and you don't know what it means, LEAVE IT ALONE and
652 only toggle the bits you want to toggle. This will allow for upward
655 If the room is a private room, you have the option of causing all users who
656 currently have access, to forget the room. If you want to do this, set the
657 "bump" flag to 1, otherwise set it to 0.
662 This command is used to get the name of the Room Aide for the current room.
663 It will return ERROR+NOT_LOGGED_IN if no user is logged in, ERROR if there
664 is no current room, or OK if the command succeeded. Along with OK there will
665 be returned one parameter: the name of the Room Aide.
670 The opposite of GETA, used to set the Room Aide for the current room. One
671 parameter should be passed, which is the name of the user who is to be the
672 new Room Aide. Under Citadel/UX, this command may only be executed by Aides
673 and by the *current* Room Aide for the room. Return codes possible are:
674 ERROR+NOT_LOGGED_IN (Not logged in.)
675 ERROR+HIGHER_ACCESS_REQUIRED (Higher access required.)
676 ERROR+NOT_HERE (No current room, or room cannot be edited.
677 Under Citadel/UX, the Lobby> Mail> and Aide> rooms are non-editable.)
678 OK (Command succeeded.)
681 ENT0 (ENTer message, mode 0)
683 This command is used to enter messages into the system. It accepts four
686 0 - Post flag. This should be set to 1 to post a message. If it is
687 set to 0, the server only returns OK or ERROR (plus any flags describing
688 the error) without reading in a message. Client software should, in fact,
689 perform this operation at the beginning of an "enter message" command
690 *before* starting up its editor, so the user does not end up typing a message
691 in vain that will not be permitted to be saved. If it is set to 2, the
692 server will accept an "apparent" post name if the user is privileged enough.
693 This post name is arg 4.
694 1 - Recipient. This argument is utilized only for private mail messages.
695 It is ignored for public messages. It contains, of course, the name of the
696 recipient of the message.
697 2 - Anonymous flag. This argument is ignored unless the room allows
698 anonymous messages. In such rooms, this flag may be set to 1 to flag a
699 message as anonymous, otherwise 0 for a normal message.
700 3 - Format type. Any valid Citadel/UX format type may be used (this will
701 typically be 0; see the MSG0 command above).
702 4 - Post name. When postflag is 2, this is the name you are posting as.
703 This is an Aide only command.
705 Possible result codes:
706 OK - The request is valid. (Client did not set the "post" flag, so the
707 server will not read in message text.) If the message is an e-mail with
708 a recipient, the text that follows the OK code will contain the exact name
709 to which mail is being sent. The client can display this to the user. The
710 implication here is that the name that the server returns will contain the
711 correct upper and lower case characters. In addition, if the recipient is
712 having his/her mail forwarded, the forwarding address will be returned.
713 SEND_LISTING - The request is valid. The client should now transmit
714 the text of the message (ending with a 000 on a line by itself, as usual).
715 ERROR - Miscellaneous error. (Explanation probably follows.)
716 ERROR + NOT_LOGGED_IN - Not logged in.
717 ERROR + HIGHER_ACCESS_REQUIRED - Higher access is required. An
718 explanation follows, worded in a form that can be displayed to the user.
719 ERROR + NO_SUCH_USER - The specified recipient does not exist.
722 RINF (read Room INFormation file)
724 Each room has associated with it a text file containing a description of
725 the room, perhaps containing its intended purpose or other important
726 information. The info file for the Lobby> (the system's base room) is
727 often used as a repository for system bulletins and the like.
729 This command, which accepts no arguments, is simply used to read the info
730 file for the current room. It will return LISTING_FOLLOWS followed by
731 the text of the message (always in format type 0) if the request can be
732 honored, or ERROR if no info file exists for the current room (which is
733 often the case). Other error description codes may accompany this result.
735 When should this command be used? This is, of course, up to the discretion
736 of client software authors, but in Citadel it is executed in two situations:
737 the first time the user ever enters a room; and whenever the contents of the
738 file change. The latter can be determined from the result of a GOTO command,
739 which will tell the client whether the file needs to be read (see GOTO above).
742 DELE (DELEte a message)
744 Delete a message from the current room. The one argument that should be
745 passed to this command is the message number of the message to be deleted.
746 The return value will be OK if the message was deleted, or an ERROR code.
747 If the delete is successful, the message's reference count is decremented, and
748 if the reference count reaches zero, the message is removed from the message
752 MOVE (MOVE or copy a message to a different room)
754 Move a message to a different room. The two arguments that should be passed
755 to this command are the message number of the message to be deleted, and the
756 name of the target room. If the operation succeeds, the message will be
757 deleted from the current room and moved to the target room. An ERROR code
758 usually means that either the user does not have permission to perform this
759 operation, or that the target room does not exist.
761 In Citadel/UX 5.55 and above, a third argument may be specified: 0 or 1 to
762 designate whether the message should be moved (0) or copied (1) to the target
763 room. In the case of a "copy" operation, the message's reference count is
764 incremented, and a pointer to the message will exist in both the source *and*
765 target rooms. In the case of a "move" operation, the message pointer is
766 deleted from the source room and the reference count remains the same.
769 KILL (KILL current room)
771 This command deletes the current room. It accepts a single argument, which
772 should be nonzero to actually delete the room, or zero to merely check
773 whether the room can be deleted.
775 Once the room is deleted, the current room is undefined. It is suggested
776 that client software immediately GOTO another room (usually _BASEROOM_)
777 after this command completes.
779 Possible return codes:
781 OK - room has been deleted (or, if checking only, request is valid).
782 ERROR+NOT_LOGGED_IN - no user is logged in.
783 ERROR+HIGHER_ACCESS_REQUIRED - not enough access to delete rooms.
784 ERROR+NOT_HERE - this room can not be deleted.
787 CRE8 (CRE[ate] a new room)
789 This command is used to create a new room. Like some of the other
790 commands, it provides a mechanism to first check to see if a room can be
791 created before actually executing the command. CRE8 accepts the following
794 0 - Create flag. Set this to 1 to actually create the room. If it is
795 set to 0, the server merely checks that there is a free slot in which to
796 create a new room, and that the user has enough access to create a room. It
797 returns OK if the client should go ahead and prompt the user for more info,
798 or ERROR or ERROR+HIGHER_ACCESS_REQUIRED if the command will not succeed.
799 1 - Name for new room.
800 2 - Access type for new room:
802 1 - Private; can be entered by guessing the room's name
803 2 - Private; can be entered by knowing the name *and* password
804 3 - Private; invitation only (sometimes called "exclusive")
805 3 - Password for new room (if it is a type 2 room)
806 4 - Floor number on which the room should reside (optional)
808 If the create flag is set to 1, the room is created (unless something
809 went wrong and an ERROR return is sent), and the server returns OK, but
810 the session is **not** automatically sent to that room. The client still
811 must perform a GOTO command to go to the new room.
814 FORG (FORGet the current room)
816 This command is used to forget (zap) the current room. For those not
817 familiar with Citadel, this terminology refers to removing the room from
818 a user's own known rooms list, *not* removing the room itself. After a
819 room is forgotten, it no longer shows up in the user's known room list,
820 but it will exist in the user's forgotten room list, and will return to the
821 known room list if the user goes to the room (in Citadel, this is
822 accomplished by explicitly typing the room's name in a <.G>oto command).
824 The command takes no arguments. If the command cannot execute for any
825 reason, ERROR will be returned. ERROR+NOT_LOGGED_IN or ERROR+NOT_HERE may
826 be returned as they apply.
828 If the command succeeds, OK will be returned. At this point, the current
829 room is **undefined**, and the client software is responsible for taking
830 the user to another room before executing any other room commands (usually
831 this will be _BASEROOM_ since it is always there).
834 MESG (read system MESsaGe)
836 This command is used to display system messages and/or help files. The
837 single argument it accepts is the name of the file to display. IT IS CASE
838 SENSITIVE. Citadel/UX looks for these files first in the "messages"
839 subdirectory and then in the "help" subdirectory.
841 If the file is found, LISTING_FOLLOWS is returned, followed by a pathname
842 to the file being displayed. Then the message is printed, in format type 0
843 (see MSG0 command for more information on this). If the file is not found,
846 There are some "well known" names of system messages which client software
847 may expect most servers to carry:
849 hello - Welcome message, to be displayed before the user logs in.
850 changepw - To be displayed whenever the user is prompted for a new
851 password. Warns about picking guessable passwords and such.
852 register - Should be displayed prior to the user entering registration.
853 Warnings about not getting access if not registered, etc.
854 help - Main system help file.
855 goodbye - System logoff banner; display when user logs off.
856 roomaccess - Information about how public rooms and different types of
857 private rooms function with regards to access.
858 unlisted - Tells users not to choose to be unlisted unless they're
859 really paranoid, and warns that aides can still see
860 unlisted userlog entries.
862 Citadel/UX provides these for the Citadel/UX Unix text client. They are
863 probably not very useful for other clients:
865 mainmenu - Main menu (when in idiot mode).
870 saveopt - Options to save a message, abort, etc.
871 entermsg - Displayed just before a message is entered, when in
875 GNUR (Get Next Unvalidated User)
877 This command shows the name of a user that needs to be validated. If there
878 are no unvalidated users, OK is returned. Otherwise, MORE_DATA is returned
879 along with the name of the first unvalidated user the server finds. All of
880 the usual ERROR codes may be returned as well (for example, if the user is
881 not an Aide and cannot validate users).
883 A typical "Validate New Users" command would keep executing this command,
884 and then validating each user it returns, until it returns OK when all new
885 users have been validated.
888 GREG (Get REGistration for user)
890 This command retrieves the registration info for a user, whose name is the
891 command's sole argument. All the usual error messages can be returned. If
892 the command succeeds, LISTING_FOLLOWS is returned, followed by the user's name
893 (retrieved from the userlog, with the right upper and lower case etc.) The
894 contents of the listing contains one field per line, followed by the usual
895 000 on the last line.
897 The following lines are defined. Others WILL be added in the futre, so all
898 software should be written to read the lines it knows about and then ignore
904 Line 4: Street address or PO Box
905 Line 5: City/town/village/etc.
906 Line 6: State/province/etc.
908 Line 8: Telephone number
910 Line 10: Internet e-mail address
912 Users without Aide privileges may retrieve their own registration using
913 this command. This can be accomplished either by passing the user's own
914 name as the argument, or the string "_SELF_". The command will always
915 succeed when used in this manner, unless no user is logged in.
920 This command is used to validate users. Obviously, it can only be executed
921 by users with Aide level access. It should be passed two parameters: the
922 name of the user to validate, and the desired access level
924 If the command succeeds, OK is returned. The user's access level is changed
925 and the "need validation" bit is cleared. If the command fails for any
926 reason, ERROR, ERROR+NO_SUCH_USER, or ERROR+HIGHER_ACCESS_REQUIRED will be
930 EINF (Enter INFo file for room)
932 Transmit the info file for the current room with this command. EINF uses
933 a boolean flag (1 or 0 as the first and only argument to the command) to
934 determine whether the client actually wishes to transmit a new info file, or
935 is merely checking to see if it has permission to do so.
937 If the command cannot succeed, it returns ERROR.
938 If the client is only checking for permission, and permission will be
939 granted, OK is returned.
940 If the client wishes to transmit the new info file, SEND_LISTING is
941 returned, and the client should transmit the text of the info file, ended
942 by the usual 000 on a line by itself.
947 This is a simple user listing. It always succeeds, returning
948 LISTING_FOLLOWS followed by zero or more user records, 000 terminated. The
949 fields on each line are as follows:
954 4. Date/time of last login (Unix format)
957 7. Password (listed only if the user requesting the list is an Aide)
959 Unlisted entries will also be listed to Aides logged into the server, but
960 not to ordinary users.
963 REGI (send REGIstration)
965 Clients will use this command to transmit a user's registration info. If
966 no user is logged in, ERROR+NOT_LOGGED_IN is returned. Otherwise,
967 SEND_LISTING is returned, and the server will expect the following information
968 (terminated by 000 on a line by itself):
971 Line 2: Street address or PO Box
972 Line 3: City/town/village/etc.
973 Line 4: State/province/etc.
975 Line 6: Telephone number
976 Line 7: e-mail address
979 CHEK (CHEcK various things)
981 When logging in, there are various things that need to be checked. This
982 command will return ERROR+NOT_LOGGED_IN if no user is logged in. Otherwise
983 it returns OK and the following parameters:
985 0: Number of new private messages in Mail>
986 1: Nonzero if the user needs to register
987 2: (Relevant to Aides only) Nonzero if new users require validation
992 This command deletes a file from the room's directory, if there is one. The
993 name of the file to delete is the only parameter to be supplied. Wildcards
994 are not acceptable, and any slashes in the filename will be converted to
995 underscores, to prevent unauthorized access to neighboring directories. The
996 possible return codes are:
998 OK - Command succeeded. The file was deleted.
999 ERROR+NOT_LOGGED_IN - Not logged in.
1000 ERROR+HIGHER_ACCESS_REQUIRED - Not an Aide or Room Aide.
1001 ERROR+NOT_HERE - There is no directory in this room.
1002 ERROR+FILE_NOT_FOUND - Requested file was not found.
1007 This command is similar to DELF, except that it moves a file (and its
1008 associated file description) to another room. It should be passed two
1009 parameters: the name of the file to move, and the name of the room to move
1010 the file to. All of the same return codes as DELF may be returned, and also
1011 one additional one: ERROR+NO_SUCH_ROOM, which means that the target room
1012 does not exist. ERROR+NOT_HERE could also mean that the target room does
1013 not have a directory.
1016 NETF (NETwork send a File)
1018 This command is similar to MOVF, except that it attempts to send a file over
1019 the network to another system. It should be passed two parameters: the name
1020 of the file to send, and the node name of the system to send it to. All of
1021 the same return codes as MOVF may be returned, except for ERROR+NO_SUCH_ROOM.
1022 Instead, ERROR+NO_SUCH_SYSTEM may be returned if the name of the target
1025 The name of the originating room will be sent along with the file. Most
1026 implementations will look for a room with the same name at the receiving end
1027 and attempt to place the file there, otherwise it goes into a bit bucket room
1028 for miscellaneous files. This is, however, beyond the scope of this document;
1029 see elsewhere for more details.
1032 RWHO (Read WHO's online)
1034 Displays a list of all users connected to the server. No error codes are
1035 ever returned. LISTING_FOLLOWS will be returned, followed by zero or more
1036 lines containing the following three fields:
1038 0 - Session ID. Citadel/UX fills this with the pid of a server program.
1040 2 - The name of the room the user is currently in. This field might not
1041 be displayed (for example, if the user is in a private room) or it might
1042 contain other information (such as the name of a file the user is
1044 3 - (server v4.03 and above) The name of the host the client is connecting
1045 from, or "localhost" if the client is local.
1046 4 - (server v4.04 and above) Description of the client software being used
1047 5 - The last time, locally to the server, that a command was received from
1048 this client (Note: NOOP's don't count)
1049 6 - The last command received from a client. (NOOP's don't count)
1050 7 - Session flags. These are: + (spoofed address), - (STEALTH mode), *
1051 (posting) and . (idle). (Citserver 5.02 and above)
1053 The listing is terminated, as always, with the string "000" on a line by
1057 OPEN (OPEN a file for download)
1059 This command is used to open a file for downloading. Only one download
1060 file may be open at a time. The only argument to this command is the name
1061 of the file to be opened. The user should already be in the room where the
1062 file resides. Possible return codes are:
1065 ERROR+NOT_HERE (no directory in this room)
1066 ERROR+FILE_NOT_FOUND (could not open the file)
1070 If the file is successfully opened, OK will be returned, along with the
1071 size (in bytes) of the file, the time of last modification (if applicable),
1072 the filename (if known), and the MIME type of the file (if known).
1075 CLOS (CLOSe the download file)
1077 This command is used to close the download file. It returns OK if the
1078 file was successfully closed, or ERROR if there wasn't any file open in the
1082 READ (READ from the download file)
1084 Two arguments are passed to this command. The first is the starting position
1085 in the download file, and the second is the total number of bytes to be
1086 read. If the operation can be performed, BINARY_FOLLOWS will be returned,
1087 along with the number of bytes to follow. Then, immediately following the
1088 newline, will be that many bytes of binary data. The client *must* read
1089 exactly that number of bytes, otherwise the client and server will get out
1092 If the operation cannot be performed, any of the usual error codes will be
1096 UOPN (OPeN a file for Uploading)
1098 This command is similar to OPEN, except that this one is used when the
1099 client wishes to upload a file to the server. The first argument is the name
1100 of the file to create, and the second argument is a one-line comment
1101 describing the contents of the file. Only one upload file may be open at a
1102 time. Possible return codes are:
1105 ERROR+NOT_HERE (no directory in this room)
1106 ERROR+FILE_NOT_FOUND (a name must be specified)
1107 ERROR (miscellaneous errors)
1108 ERROR+ALREADY_EXISTS (a file with the same name already exists)
1111 If OK is returned, the command has succeeded and writes may be performed.
1114 UCLS (CLoSe the Upload file)
1116 Close the file opened with UOPN. An argument of "1" should be passed to
1117 this command to close and save the file; otherwise, the transfer will be
1118 considered aborted and the file will be deleted. This command returns OK
1119 if the operation succeeded or ERROR if it did not.
1122 WRIT (WRITe to the upload file)
1124 If an upload file is open, this command may be used to write to it. The
1125 argument passed to this command is the number of bytes the client wishes to
1126 transmit. An ERROR code will be returned if the operation cannot be
1129 If the operation can be performed, SEND_BINARY will be returned, followed
1130 by the number of bytes the server is expecting. The client must then transmit
1131 exactly that number of bytes. Note that in the current implementation, the
1132 number of bytes the server is expecting will always be the number of bytes
1133 the client requested to transmit, but the client software should never assume
1134 that this will always happen, in case changes are made later.
1137 QUSR (Query for a USeR)
1139 This command is used to check to see if a particular user exists. The only
1140 argument to this command is the name of the user being searched for. If
1141 the user exists, OK is returned, along with the name of the user in the userlog
1142 (so the client software can learn the correct upper/lower casing of the name
1143 if necessary). If the user does not exist, ERROR+NO_SUCH_USER is returned.
1144 No login or current room is required to utilize this command.
1147 OIMG (Open an IMaGe file)
1149 Open an image (graphics) file for downloading. Once opened, the file can be
1150 read as if it were a download file. This implies that an image and a download
1151 cannot be opened at the same time. OIMG returns the same result codes as OPEN.
1153 All images will be in GIF (Graphics Interchange Format). In the case of
1154 Citadel/UX, the server will convert the supplied filename to all lower case,
1155 append the characters ".gif" to the filename, and look for it in the "images"
1156 subdirectory. As with the MESG command, there are several "well known"
1157 images which are likely to exist on most servers:
1159 hello - "Welcome" graphics to be displayed alongside MESG "hello"
1160 goodbye - Logoff banner graphics to be displayed alongside MESG "goodbye"
1161 background - Background image (usually tiled) for graphical clients
1163 The following "special" image names are defined in Citadel/UX server version
1166 _userpic_ - Picture of a user (send the username as the second argument)
1167 _floorpic_ - A graphical floor label (send the floor number as the second
1168 argument). Clients which request a floor picture will display
1169 the picture *instead* of the floor name.
1170 _roompic_ - A graphic associated with the *current* room. Clients which
1171 request a room picture will display the picture in *addition*
1172 to the room name (i.e. it's used for a room banner, as
1173 opposed to the floor picture's use in a floor listing).
1176 NETP (authenticate as network session with system NET Password)
1178 This command is used by client software to identify itself as a transport
1179 session for IGnet/Open BBS to BBS networking. It should be called with
1180 two arguments: the node name of the calling system, and the system net
1181 password for the server. If the authentication succeeds, NETP will return
1182 OK, otherwise, it returns ERROR.
1185 NUOP (Network Upload OPen file)
1187 Open a network spool file for uploading. The client must have already
1188 identified itself as a network session using the NETP command. If the command
1189 returns OK, the client may begin transmitting IGnet/Open spool data using
1190 a series of WRIT commands. When a UCLS command is issued, the spooled data
1191 is entered into the BBS if the argument to UCLS is 1 or discarded if the
1192 argument to UCLS is 0. If the client has not authenticated itself with a
1193 NETP command, ERROR+HIGHER_ACCESS_REQUIRED will be returned.
1196 NDOP (Network Download OPen file)
1198 Open a network spool file for downloading. The client must have already
1199 identified itself as a network session using the NETP command. If the command
1200 returns OK, the client may begin receiving IGnet/Open spool data using
1201 a series of READ commands. When a CLOS command is issued, the spooled data
1202 is deleted from the server and may not be read again. If the client has not
1203 authenticated itself with a NETP command, ERROR+HIGHER_ACCESS_REQUIRED will
1207 LFLR (List all known FLooRs)
1209 On systems supporting floors, this command lists all known floors. The
1210 command accepts no parameters. It will return ERROR+NOT_LOGGED_IN if no
1211 user is logged in. Otherwise it returns LISTING_FOLLOWS and a list of
1212 the available floors, each line consisting of three fields:
1214 1. The floor number associated with the floor
1215 2. The name of the floor
1216 3. Reference count (number of rooms on this floor)
1219 CFLR (Create a new FLooR)
1221 This command is used to create a new floor. It should be passed two
1222 arguments: the name of the new floor to be created, and a 1 or 0 depending
1223 on whether the client is actually creating a floor or merely checking to
1224 see if it has permission to create the floor. The user must be logged in
1225 and have Aide privileges to create a floor.
1227 If the command succeeds, it will return OK followed by the floor number
1228 associated with the new floor. Otherwise, it will return ERROR (plus perhaps
1229 HIGHER_ACCESS_REQUIRED, ALREADY_EXISTS, or INVALID_FLOOR_OPERATION)
1230 followed by a description of why the command failed.
1235 This command is used to delete a floor. It should be passed two
1236 argument: the *number* of the floor to be deleted, and a 1 or 0 depending
1237 on whether the client is actually deleting the floor or merely checking to
1238 see if it has permission to delete the floor. The user must be logged in
1239 and have Aide privileges to delete a floor.
1241 Floors that contain rooms may not be deleted. If there are rooms on a floor,
1242 they must be either deleted or moved to different floors first. This implies
1243 that the Main Floor (floor 0) can never be deleted, since Lobby>, Mail>, and
1244 Aide> all reside on the Main Floor and cannot be deleted.
1246 If the command succeeds, it will return OK. Otherwise it will return
1247 ERROR (plus perhaps HIGHER_ACCESS_REQUIRED or INVALID_FLOOR_OPERATION)
1248 followed by a description of why the command failed.
1253 Edit the parameters of a floor. The client may pass one or more parameters
1256 1. The number of the floor to be edited
1257 2. The desired new name
1259 More parameters may be added in the future. Any parameters not passed to
1260 the server will remain unchanged. A minimal command would be EFLR and a
1261 floor number -- which would do nothing. EFLR plus the floor number plus a
1262 floor name would change the floor's name.
1264 If the command succeeds, it will return OK. Otherwise it will return
1265 ERROR (plus perhaps HIGHER_ACCESS_REQUIRED or INVALID_FLOOR_OPERATION)
1268 IDEN (IDENtify the client software)
1270 The client software has the option to identify itself to the server.
1271 Currently, the server does nothing with this information except to write
1272 it to the syslog to satisfy the system administrator's curiosity. Other
1273 uses might become apparent in the future.
1275 The IDEN command should contain five fields: a developer ID number (same as
1276 the server developer ID numbers in the INFO command -- please obtain one if
1277 you are a new developer), a client ID number (which does not have to be
1278 globally unique - only unique within the domain of the developer number),
1279 a version number, a free-form text string describing the client, and the name
1280 of the host the user is located at.
1282 It is up to the server to determine whether to accept the host name or to
1283 use the host name it has detected itself. Generally, if the client is
1284 running on a trusted host (either localhost or a well-known publically
1285 accessible client) it should use the host name transmitted by IDEN,
1286 otherwise it should use the host name it has detected itself.
1288 IDEN always returns OK, but since that's the only way it ever returns
1289 there's no point in checking the result code.
1292 IPGM (identify as an Internal ProGraM)
1294 IPGM is a low-level command that should not be used by normal user clients.
1295 It is used for various utilities to communicate with the server on the same
1296 host. For example, the networker (netproc.c) logs onto the server as an
1297 internal program in order to fetch and store messages. Since user clients
1298 do not utilize this command (or any of its companion commands), developers
1299 writing Citadel-compatible servers need not implement it.
1301 The sole argument to IPGM is the system's internal program password. This
1302 password is generated by the setup program and stored in the config file.
1303 Since internal programs have access to the config file, they know the correct
1306 IPGM returns OK for a correct authentication or ERROR otherwise.
1309 CHAT (enter CHAT mode)
1311 This command functions differently from every other command in the system. It
1312 is used to implement multi-user chat. For this to function, a new transfer
1313 mode, called START_CHAT_MODE, is implemented. If a client does not support
1314 chat mode, it should never send a CHAT command!
1316 In chat mode, messages may arrive asynchronously from the server at any
1317 time. The client may send messages at any time. This allows the arrival of
1318 messages without the client having to poll for them. Arriving messages will
1319 be of the form "user|message", where the "user" portion is, of course, the
1320 name of the user sending the message, and "message" is the message text.
1322 Chat mode ends when the server says it ends. The server will signal the end
1323 of chat mode by transmitting "000" on a line by itself. When the client reads
1324 this line, it must immediately exit from chat mode without sending any
1325 further traffic to the server. The next transmission sent to the server
1326 will be a regular server command.
1328 The Citadel/UX server understands the following commands:
1329 /quit - Exit from chat mode (causes the server to do an 000 end)
1330 /who - List users currently in chat
1331 /whobbs - List users currently in chat and on the bbs
1332 /me - Do an irc-style action.
1333 /join - Join a new "room" in which all messages are only heard by
1334 people in that room.
1335 /msg - /msg <user> <msg> will send the msg to <user> only.
1336 /help - Print help information
1337 NOOP - Do nothing (silently)
1339 Any other non-empty string is treated as message text and will be broadcast
1340 to other users currently in chat.
1343 SEXP (Send EXPress messages)
1345 This is one of two commands which implement "express messages" (also known
1346 as "paging"). An express message is a near-real-time message sent from one
1347 logged in user to another. When an express message is sent, it will be
1348 displayed the next time the target user executes a PEXP or GEXP command.
1350 The SEXP command accepts two arguments: the name of the user to send the
1351 message to, and the text of the message. If the message is successfully
1352 transmitted, OK is returned. If the target user is not logged in or if
1353 anything else goes wrong, ERROR is returned.
1355 If the server supports extended paging, sending a zero-length message
1356 merely checks for the presence of the requested user without actually sending
1357 a message. Sending a message consisting solely of a "-" (hyphen) will cause
1358 the server to return SEND_LISTING if the requested user is logged in, and the
1359 client can then transmit a multi-line page.
1361 The reserved name "broadcast" may be used instead of a user name, to
1362 broadcast an express message to all users currently connected to the server.
1364 Do be aware that if an express message is transmitted to a user who is logged
1365 in using a client that does not check for express messages, the message will
1369 PEXP (Print EXPress messages) ***DEPRECATED***
1371 This command is deprecated; it will eventually disappear from the protocol and
1372 its use is not recommended. Please use the GEXP command instead.
1374 Called without any arguments, PEXP simply dumps out the contents
1375 of any waiting express messages. It returns ERROR if there is a problem,
1376 otherwise it returns LISTING_FOLLOWS followed by all messages.
1378 So how does the client know there are express messages waiting? It could
1379 execute a random PEXP every now and then. Or, it can check the byte in
1380 server return code messages, between the return code and the parameters. In
1381 much the same way as FTP uses "-" to signify a continuation, Citadel uses
1382 an "*" in this position to signify the presence of waiting express messages.
1385 EBIO (Enter BIOgraphy)
1387 Transmit to the server a free-form text file containing a little bit of
1388 information about the user for other users to browse. This is typically
1389 referred to as a 'bio' online. EBIO returns SEND_LISTING if it succeeds,
1390 after which the client is expected to transmit the file, or any of the usual
1391 ERROR codes if it fails.
1394 RBIO (Read BIOgraphy)
1396 Receive from the server a named user's bio. This command should be passed
1397 a single argument - the name of the user whose bio is requested. RBIO returns
1398 LISTING_FOLLOWS plus the bio file if the user exists and has a bio on file,
1399 ERROR+NO_SUCH_USER if the named user does not exist, or ERROR+FILE_NOT_FOUND
1400 if the user exists but has no bio on file.
1403 STEL (enter STEaLth mode)
1405 When in "stealth mode," a user will not show up in the "Who is online"
1406 listing (the RWHO server command). Only Aides may use stealth mode. The
1407 STEL command accepts one argument: a 1 indicating that the user wishes to
1408 enter stealth mode, or a 0 indicating that the user wishes to exit stealth
1409 mode. STEL returns OK if the command succeeded, ERROR+NOT_LOGGED_IN if no
1410 user is logged in, or ERROR+HIGHER_ACCESS_REQUIRED if the user is not an Aide.
1412 The STEL command also makes it so a user does not show up in the chat room
1416 LBIO (List users who have BIOs on file)
1418 This command is self-explanatory. Any user who has used EBIO to place a bio
1419 on file is listed. LBIO almost always returns LISTING_FOLLOWS followed by
1420 this listing, unless it experiences an internal error in which case ERROR
1424 MSG2 (read MeSsaGe, mode 2)
1426 MSG2 follows the same calling convention as MSG0. The difference between
1427 the two commands is that MSG2 outputs messages in standard RFC822 format
1428 rather than in Citadel/UX proprietary format.
1430 This command was implemented in order to make various gateway programs
1431 easier to implement, and to provide some sort of multimedia support in the
1432 future. Keep in mind that when this command is used, all messages will be
1433 output in fixed 80-column format.
1436 MSG3 (read MeSsaGe, mode 3 -- internal command)
1438 MSG3 is for use by internal programs only and should not be utilized by
1439 user-mode clients. It does require IPGM authentication. MSG3 follows the
1440 same calling convention as the other MSG commands, but upon success returns
1441 BINARY_FOLLOWS followed by a data block containing the _raw_ message format
1445 ENT3 (ENTer message, mode 3 -- internal command)
1447 ENT3 is for use by internal programs only and should not be utilized by
1448 user-mode clients. It does require IPGM authentication. This command posts
1449 a raw message straight into the message base without modification or performing
1450 any checks. It accepts the following arguments:
1452 0 - Post flag. This should be set to 1 to post a message. If it is
1453 set to 0, the server only returns OK or ERROR (plus any flags describing
1454 the error) without reading in a message. This is used to verify the operation
1455 before actually transmitting a message.
1456 1 - Recipient. This argument is utilized only for private mail messages.
1457 It is ignored for public messages. It contains, of course, the name of the
1458 recipient of the message.
1459 2 - The size (in bytes) of the message to be transmitted.
1461 ENT3 returns OK to tell the client that a message can be posted, ERROR if
1462 there would be a problem with the operation, or SEND_BINARY followed by a byte
1463 count if it is expecting the message to be transmitted.
1466 TERM (TERMinate another session)
1468 In a multithreaded environment, it sometimes becomes necessary to terminate
1469 a session that is unusable for whatever reason. The TERM command performs
1470 this task. Naturally, only Aides can execute TERM. The command should be
1471 called with a single argument: the session ID (obtained from an RWHO command)
1472 of the session to be terminated.
1474 TERM returns OK if the session was terminated, or ERROR otherwise. Note that
1475 a client program is prohibited from terminating the session it is currently
1479 NSET (Network SETup commands)
1481 Aides may use this command to configure the networker. This command's
1482 parameters are passed directly to the 'netsetup' command line utility. If
1483 netsetup returns a non-zero exit code, ERROR is returned, along with the
1484 error message (if any). If netsetup returns a zero (success) exit code,
1485 LISTING_FOLLOWS is returned, followed by zero or more lines of output (since
1486 netsetup may have information to display, such as a room or node list) and
1487 the usual '000' listing terminator.
1490 DOWN (shut DOWN the server)
1492 This command, which may only be executed by an Aide, immediately shuts down
1493 the server. It is only implemented on servers on which such an operation is
1494 possible, such as a multithreaded Citadel engine. The server does not restart.
1495 DOWN returns OK if the user is allowed to shut down the server, in which case
1496 the client program should expect the connection to be immediately broken.
1499 SCDN (Schedule or Cancel a shutDowN)
1501 SCDN sets or clears the "scheduled shutdown" flag. Pass this command a 1 or
1502 0 to respectively set or clear the flag. When the "scheduled shutdown" flag is
1503 set, the server will be shut down when there are no longer any users logged in.
1504 Any value other than 0 or 1 will not change the flag, only report its state.
1505 No users will be kicked off the system, and in fact the server is still
1506 available for new connections. The command returns ERROR if it fails;
1507 otherwise, it returns OK followed by a number representing the current state
1511 EMSG (Enter a system MeSsaGe)
1513 This is the opposite of the MESG command - it allows the creation and editing
1514 of system messages. The only argument passed to EMSG is the name of the
1515 file being transmitted. If the file exists in any system message directory
1516 on the server it will be overwritten, otherwise a new file is created. EMSG
1517 returns SEND_LISTING on success or ERROR+HIGHER_ACCESS_REQUIRED if the user
1520 Typical client software would use MESG to retrieve any existing message into
1521 an edit buffer, then present an editor to the user and run EMSG if the changes
1525 UIMG (Upload an IMaGe file)
1527 UIMG is complemenary to OIMG; it is used to upload an image to the server.
1528 The first parameter supplied to UIMG should be 0 if the client is only checking
1529 for permission to upload, or 1 if the client is actually attempting to begin
1530 the upload operation. The second argument is the name of the file to be
1531 transmitted. In Citadel/UX, the filename is converted to all lower case,
1532 appended with the characters ".gif", and stored in the "images" directory.
1534 UIMG returns OK if the client has permission to perform the requested upload,
1535 or ERROR+HIGHER_ACCESS_REQUIRED otherwise. If the client requested to begin
1536 the operation (first parameter set to 1), an upload file is opened, and the
1537 client should begin writing to it with WRIT commands, then close it with a
1540 The supplied filename should be one of:
1542 -> _userpic_ (Server will attempt to write to the user's online photo)
1543 -> Any of the "well known" filenames described in the writeup for the
1547 HCHG (Hostname CHanGe)
1549 HCHG is a command, usable by any user, that allows a user to change their RWHO
1550 host value. This will mask a client's originating hostname from normal
1551 users; access level 6 and higher see an entry right underneath the spoofed
1552 entry listing the actual hostname the user originates from.
1554 The format of an HCHG command is:
1558 If a HCHG command is successful, the value OK (200) is returned.
1561 RCHG (Roomname CHanGe)
1563 RCHG is a command, usable by any user, that allows a user to change their RWHO
1564 room value. This will mask a client's roomname from normal users; access
1565 level 6 and higher see an entry right underneath the spoofed entry listing
1566 the actual room the user is in.
1568 The format of an RCHG command is:
1572 If a RCHG command is successful, the value OK (200) is returned.
1575 UCHG (Username CHanGe)
1577 UCHG is an aide-level command which allows an aide to effectively change their
1578 username. If this value is blank, the user goes into stealth mode (see
1580 will show up as being from the real username in this mode, however. In
1581 addition, the RWHO listing will include both the spoofed and real usernames.
1583 The format of an UCHG command is:
1587 If a UCHG command is successful, the value OK (200) is returned.
1590 TIME (get server local TIME)
1592 TIME returns OK followed by the current time measured in seconds since
1593 00:00:00 GMT, Jan 1, 1970 (standard Unix format).
1595 This is used in allowing a client to calculate idle times.
1598 AGUP (Administrative Get User Parameters)
1599 ASUP (Administrative Set User Parameters)
1601 These commands are only executable by Aides and by server extensions running
1602 at system-level. They are used to get/set any and all parameters relating to
1603 a user account. AGUP requires only one argument: the name of the user in
1604 question. SGUP requires all of the parameters to be set. The parameters are
1605 as follows, and are common to both commands:
1609 2 - Flags (see citadel.h)
1614 7 - Timestamp of last call
1615 8 - Purge time (in days) for this user (or 0 to use system default)
1617 Upon success, AGUP returns OK followed by all these parameters, and ASUP
1618 simply returns OK. If the client has insufficient access to perform the
1619 requested operation, ERROR+HIGHER_ACCESS_REQUIRED is returned. If the
1620 requested user does not exist, ERROR+NO_SUCH_USER is returned.
1624 GPEX (Get Policy for message EXpiration)
1626 Returns the policy of the current room, floor, or site regarding the automatic
1627 purging (expiration) of messages. The following policies are available:
1628 0 - Fall back to the policy of the next higher level. If this is a room,
1629 use the floor's default policy. If this is a floor, use the system
1630 default policy. This is an invalid value for the system policy.
1631 1 - Do not purge messages automatically.
1632 2 - Purge by message count. (Requires a value: number of messages)
1633 3 - Purge by message age. (Requires a value: number of days)
1635 The format of this command is: GPEX <which>
1636 The value of <which> must be one of: "room" "floor" "site"
1638 If successful, GPEX returns OK followed by <policy>|<value>.
1642 SPEX (Set Polict for message EXpiration)
1644 Sets the policy of the current room, floor, or site regarding the automatic
1645 purging (expiration) of messages. See the writeup for the GPEX command for
1646 the list of available policies.
1648 The format of this command is: SPEX <which>|<policy>|<value>
1649 The value of <which> must be one of: "room" "floor" "site"
1651 If successful, GPEX returns OK; otherwise, an ERROR code is returned.
1655 CONF (get or set global CONFiguration options)
1657 Retrieves or sets various system-wide configuration and policy options. This
1658 command is only available to Aides. The sole parameter accepted is a command,
1659 which should be either GET or SET. If the GET command succeeds, CONF will
1660 return LISTING_FOLLOWS followed by the fields described below, one line at a
1661 time. If the SET command succeeds, CONF will return SEND_LISTING and expect
1662 the fields described below, one line at a time (don't worry about other fields
1663 being added in the future; if a 'short' configuration list is sent, the missing
1664 values at the end will be left unchanged on the system). If either command
1665 fails for any reason, ERROR is returned.
1667 The configuration lines are as follows:
1670 2. Fully qualified domain name
1671 3. Human-readable node name
1672 4. Landline telephone number of this system
1673 5. Flag (0 or 1) - creator of private room automatically becomes room aide
1674 6. Server connection idle timeout (in seconds)
1675 7. Initial access level for new users
1676 8. Flag (0 or 1) - require registration for new users
1677 9. Flag (0 or 1) - automatically move Problem User messages to twit room
1678 10. Name of twit room
1679 11. Text of <more> prompt
1680 12. Flag (0 or 1) - restrict access to Internet mail
1681 13. Geographic location of this system
1682 14. Name of the system administrator
1683 15. Number of maximum concurrent sessions allowed on the server
1684 16. Password for server-to-server networking
1685 17. Default purge time (in days) for users
1686 18. Default purge time (in days) for rooms
1687 19. Name of room to log express messages to (or a zero-length name for none)
1688 20. Access level required to create rooms
1689 21. Maximum message length which may be entered into the system
1690 22. Default moderation filter level for new users (-63 to +63)
1694 EXPI (EXPIre system objects)
1696 Begins purge operations for objects which, according to site policy, are
1697 "old" and should be removed. EXPI should be called with one argument, one of:
1699 "messages" (purge old messages out of each room)
1700 "users" (purge old users from the userlog)
1701 "rooms" (remove rooms which have not been posted in for some time)
1702 "visits" (purge dereferenced user/room relationship records)
1704 EXPI returns OK (probably after a long delay while it does its work) if it
1705 succeeds; otherwise it returns an ERROR code.
1707 This command is probably temporary, until we can work some sort of scheduler
1708 into the system. It is implemented in the serv_expire module.
1712 MSG4 (read MeSsaGe, mode 4 -- enumerate MIME parts)
1714 FIX ... do the writeup for this once it's done.
1718 OPNA (OPeN Attachment)
1720 Opens, as a download file, a component of a MIME-encoded message. The two
1721 parameters which must be passed to this command are the message number and the
1722 name of the desired section. If the message or section does not exist, an
1723 appropriate ERROR code will be returned; otherwise, if the open is successful,
1724 this command will succeed returning the same information as an OPEN command.
1727 GEXP (Get EXPress messages)
1729 This is a more sophisticated way of retrieving express messages than the old
1730 PEXP method. If there are no express messages waiting, PEXP returns ERROR;
1731 otherwise, it returns LISTING_FOLLOWS and the following arguments:
1733 0 - a boolean value telling the client whether there are any additional
1734 express messages waiting following this one
1735 1 - a Unix-style timestamp
1736 2 - flags (see server.h for more info)
1737 3 - the name of the sender
1738 4 - the node this message originated on (for future support of PIP, ICQ, etc.)
1740 The text sent to the client will be the body of the express message.
1742 So how does the client know there are express messages waiting? It could
1743 execute a random GEXP every now and then. Or, it can check the byte in
1744 server return code messages, between the return code and the parameters. In
1745 much the same way as FTP uses "-" to signify a continuation, Citadel uses
1746 an "*" in this position to signify the presence of waiting express messages.
1750 CICQ (Citadel ICQ metaclient setup)
1753 This command is most likely a temporary one. Citadel will eventually have
1754 more robust functionality for abstract configuration screens, and when that
1755 happens, this command will certainly be migrated there. If you're developing
1756 a client, don't spend a lot of time working on ICQ screens.
1758 If a Citadel server has the ICQ Metaclient installed, this command is used
1759 to configure it. It has several usages:
1763 This tells Citadel the user's ICQ uin (second argument) and password (third
1764 argument). When called in this fashion, CICQ will return either OK or ERROR.
1765 It should be noted, however, that the only way an ERROR code can be returned
1766 is if the uin and/or password is not supplied. Authentication failures cannot
1767 be immediately detected, because the ICQ protocol is asynchronous.
1771 Request the current contact list. If successful, CICQ will return
1772 LISTING_FOLLOWS followed by zero or more contacts in the format
1778 Upload a new contact list. If successful, CICQ will return SEND_LISTING
1779 after which the client should transmit zero or more uin's, one per line. The
1780 server will then attempt to contact the ICQ server to determine nicknames
1785 Always returns OK followed by a 1 (connected to ICQ) or 0 (not connected).
1790 FSCK (check message base reference counts)
1792 Verify, via the long way, that all message referenmce counts are correct. If
1793 the user has permission to do this then LISTING_FOLLOWS is returned, followed
1794 by a transcript of the run. Otherwise ERROR is returned.
1797 DEXP (Disable EXPress messages)
1799 DEXP sets or clears the "disable express messages" flag. Pass this command a
1800 1 or 0 to respectively set or clear the flag. When the "disable express
1801 messages" flag is set, no one except Aides may send the user express messages.
1802 Any value other than 0 or 1 will not change the flag, only report its state.
1803 The command returns ERROR if it fails; otherwise, it returns OK followed by a
1804 number representing the current state of the flag.