1 SESSION LAYER PROTOCOL FOR CITADEL/UX
2 (c) 1995-1998 by Art Cancro 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 <ajc@uncnsrd.mt-kisco.ny.us>.
29 CONNECTING TO A SERVER
30 ----------------------
32 The protocols used below the session layer are beyond the scope of this
33 document, but we will briefly cover a few of the currently used methods.
34 Keep in mind that the server program itself does not speak any protocols
35 lower than the session layer. Instead, it reads all input from stdin, and
36 writes all output to stdout. This implies that it is the responsibility of
37 other programs to provide a usable transport to the client programs.
39 One way to connect to a server is to use a set of pipes. This does of
40 course assume that the client and server are running on the same computer.
41 When the client starts up, the first thing that it does is create two pipes,
42 which it temporarily dup()'s to stdin and stdout. Then it proceeds to
43 fork() and exec() to a copy of the server program, which inherits the
44 pipes as its standard input and output - exactly the desired effect. The
45 client program can then re-connect its own stdin and stdout to where they're
46 supposed to be, and use the pipes to send and receive server messages.
48 Another way is to use TCP/IP. Under Unix-like systems this is easily
49 accomplished using the "inetd" superserver program, which can take programs
50 like the Citadel/UX server and offer connections to clients over a TCP or
51 UDP port. See the install documentation (or the inetd documentation from
52 your OS) for information on how to do this. Always use TCP ports for
53 Citadel/UX sessions. Since our session layer assumes a clean, reliable,
54 sequenced connection, the use of UDP would render the server unstable and
55 unusable. When operating in a TCP/IP environment, the port number officially
56 assigned to Citadel is 504.
59 GENERAL INFORMATION ABOUT THE SERVER
60 ------------------------------------
62 The server is connection-oriented and stateful: each client requires its own
63 connection to a server process, and when a command is sent, the client must
64 read the response, and then transfer data or change modes if necessary.
66 The session layer is very much like other Internet protocols such as SMTP
67 or NNTP. A client program sends one-line commands to the server, and the
68 server responds with a three-digit numeric result code followed by a message
69 describing what happened. This cycle continues until the end of the
72 Unlike protocols such as FTP, all data transfers occur in-band. This means
73 that the same connection that is used for exchange of client/server
74 messages, will also be used to transfer data back and forth. (FTP opens a
75 separate connection for data transfers.) We do this to allow the server to
76 function over transports which can only handle one session at a time (such
77 as a dialup connection).
83 The server will respond to all commands with a 3-digit result code, which
84 will be the first three characters on the line. The rest of the line may
85 contain a human-readable string explaining what happened. (Some client
86 software will display some of these strings to the user.)
88 The first digit is the most important. The following codes are defined for
89 this position: ERROR, OK, MORE_DATA, LISTING_FOLLOWS, and SEND_LISTING.
91 The second and third digits may provide a reason as to why a command
92 succeeded or failed. See ipcdef.h for the available codes.
94 ERROR means the command did not complete.
95 OK means the command executed successfully.
96 MORE_DATA means the command executed partially. Usually this means that
97 another command needs to be executed to complete the operation. For example,
98 sending the USER command to log in a user usually results in a MORE_DATA
99 result code, because the client needs to execute a PASS command to send the
100 password and complete the login.
101 LISTING_FOLLOWS means that after the server response, the server will
102 output a listing of some sort. The client *must* read the listing, whether
103 it wants to or not. The end of the listing is signified by the string
104 "000" on a line by itself.
105 SEND_LISTING is the opposite of LISTING_FOLLOWS. It means that the client
106 should begin sending a listing of some sort. The client *must* send something,
107 even if it is an empty listing. Again, the listing ends with "000" on a line
114 Zero or more parameters may be passed to a command. When more than one
115 parameter is passed to a command, they should be separated by the "|"
118 In this example, we're using the "SETU" command and passing three
119 parameters: 80, 24, and 260.
121 When the server spits out data that has parameters, if more than one
122 parameter is returned, they will be separated by the "|" symbol like
125 In this example, we just executed the "GETU" command, and it returned us
126 an OK result code (the '2' in the 200) and three parameters: 80, 24, and
133 This is a listing of all the commands that a Citadel/UX server can execute.
138 This command does nothing. It takes no arguments and always returns
139 OK. It is intended primarily for testing and development, but it might also
140 be used as a "keep alive" command to prevent the server from timing out, if
141 it's running over a transport that needs this type of thing.
144 ECHO (ECHO something)
146 This command also does nothing. It simply returns OK followed by whatever
152 Terminate the server connection. This command takes no arguments. It
153 returns OK and closes the connection immediately.
158 Log out the user without closing the server connection. It always returns
159 OK even if no user is logged in.
162 USER (send USER name)
164 The first step in logging in a user. This command takes one argument: the
165 name of the user to be logged in. If the user exists, a MORE_DATA return
166 code will be sent, which means the client should execute PASS as the next
167 command. If the user does not exist, ERROR is returned.
172 The second step in logging in a user. This command takes one argument: the
173 password for the user we are attempting to log in. If the password doesn't
174 match the correct password for the user we specified for the USER command,
175 or if a USER command has not been executed yet, ERROR is returned. If the
176 password is correct, OK is returned and the user is now logged in... and
177 most of the other server commands can now be executed. Along with OK, the
178 following parameters are returned:
180 0 - The user's name (in case the client wants the right upper/lower casing)
181 1 - The user's current access level
184 4 - Various flags (see citadel.h)
188 NEWU (create NEW User account)
190 This command creates a new user account and logs it in. The argument to
191 this command will be the name of the account. No case conversion is done
192 on the name. Note that the new account is installed with a default
193 configuration, and no password, so the client should immediately prompt the
194 user for a password and install it with the SETP command as soon as this
195 command completes. This command returns OK if the account was created and
196 logged in, or ERROR if another user already exists with this name. If OK,
197 it will also return the same parameters that PASS returns.
200 AUTO (AUTOmatic login **OBSLETE** )
202 Citadel/UX no longer supports this type of authentication. It was formerly
203 used to automatically authenticate a user based on the user ID under which
204 the server was running. Due to the new multithreaded architecture of the
205 server, this is no longer possible.
208 SETP (SET new Password)
210 This command sets a new password for the currently logged in user. The
211 argument to this command will be the new password. The command always
212 returns OK, unless the client is not logged in, in which case it will return
216 LKRN (List Known Rooms with New messages)
218 List known rooms with new messages. If the client is not logged in, ERROR
219 is returned. Otherwise, LISTING_FOLLOWS is returned, followed by the room
220 listing. Each line in the listing contains the full name of a room, followed
221 by the '|' symbol, and then a number that may contain the following bits:
224 #define QR_PERMANENT 1 /* Room does not purge */
225 #define QR_PRIVATE 4 /* Set for any type of private room */
226 #define QR_PASSWORDED 8 /* Set if there's a password too */
227 #define QR_GUESSNAME 16 /* Set if it's a guessname room */
228 #define QR_DIRECTORY 32 /* Directory room */
229 #define QR_UPLOAD 64 /* Allowed to upload */
230 #define QR_DOWNLOAD 128 /* Allowed to download */
231 #define QR_VISDIR 256 /* Visible directory */
232 #define QR_ANONONLY 512 /* Anonymous-Only room */
233 #define QR_ANON2 1024 /* Anonymous-Option room */
234 #define QR_NETWORK 2048 /* Shared network room */
235 #define QR_PREFONLY 4096 /* Preferred status needed to enter */
236 #define QR_READONLY 8192 /* Aide status required to post */
239 Other bits may be defined in the future. The listing terminates, as with
240 all listings, with "000" on a line by itself.
242 Version 4.01 and above only:
244 Starting with version 4.01 and above, floors are supported. The first
245 argument to LKRN should be the number of the floor to list rooms from. Only
246 rooms from this floor will be listed. If no arguments are passed to LKRN, or
247 if the floor number requested is (-1), rooms on all floors will be listed.
249 The third field displayed on each line is the number of the floor the room
250 is on. The LFLR command should be used to associate floor numbers with
255 LKRO (List Known Rooms with Old [no new] messages)
257 This follows the same usage and format as LKRN.
260 LZRM (List Zapped RooMs)
262 This follows the same usage and format as LKRN and LKRO.
265 LKRA (List All Known Rooms)
267 Same format. Lists all known rooms, with or without new messages.
270 LRMS (List all accessible RooMS)
272 Again, same format. This command lists all accessible rooms, known and
273 forgotten, with and without new messages. It does not, however, list
274 inaccessible private rooms.
277 GETU (GET User configuration)
279 This command retrieves the screen dimensions and user options for the
280 currently logged in account. ERROR will be returned if no user is logged
281 in, of course. Otherwise, OK will be returned, followed by three parameters.
282 The first parameter is the user's screen width, the second parameter is the
283 user's screen height, and the third parameter is a bag of bits with the
286 #define US_LASTOLD 16 /* Print last old message with new */
287 #define US_EXPERT 32 /* Experienced user */
288 #define US_UNLISTED 64 /* Unlisted userlog entry */
289 #define US_NOPROMPT 128 /* Don't prompt after each message */
290 #define US_DISAPPEAR 512 /* Use "disappearing msg prompts" */
291 #define US_PAGINATOR 2048 /* Pause after each screen of text */
293 There are other bits, too, but they can't be changed by the user (see below).
296 SETU (SET User configuration)
298 This command does the opposite of SETU: it takes the screen dimensions and
299 user options (which were probably obtained with a GETU command, and perhaps
300 modified by the user) and writes them to the user account. This command
301 should be passed three parameters: the screen width, the screen height, and
302 the option bits (see above).
304 Note that there exist bits here which are not listed in this document. Some
305 are flags that can only be set by Aides or the system administrator. SETU
306 will ignore attempts to toggle these bits. There also may be more user
307 settable bits added at a later date. To maintain later downward compatibility,
308 the following procedure is suggested:
310 1. Execute GETU to read the current flags
311 2. Toggle the bits that we know we can toggle
312 3. Execute SETU to write the flags
314 If we are passed a bit whose meaning we don't know, it's best to leave it
315 alone, and pass it right back to the server. That way we can use an old
316 client on a server that uses an unknown bit without accidentally clearing
317 it every time we set the user's configuration.
322 This command is used to goto a new room. When the user first logs in (login
323 is completed after execution of the PASS command) this command is
324 automatically and silently executed to take the user to the first room in the
325 system (usually called the Lobby).
327 This command can be passed one or two parameters. The first parameter is,
328 of course, the name of the room. Although it is not case sensitive, the
329 full name of the room must be used. Wildcard matching or unique string
330 matching of room names should be the responsibility of the client.
332 Note that the reserved room name "_BASEROOM_" can be passed to the server
333 to cause the goto command to take the user to the first room in the system,
334 traditionally known as the Lobby>. As long as a user is logged in, a
335 GOTO command to _BASEROOM_ is guaranteed to succeed. This is useful to
336 allow client software to return to the base room when it doesn't know
339 Citadel/UX server v4.01 and above, also has two additional reserved room
340 names. "_MAIL_" translates to the system's designated room for e-mail
341 messages, and "_BITBUCKET_" goes to whatever room has been chosen for messages
344 The second (and optional) parameter is a password, if one is required for
345 access to the room. This allows for all types of rooms to be accessed via
346 this command: for public rooms, invitation-only rooms to which the user
347 has access, and preferred users only rooms to which the user has access, the
348 room will appear in a room listing. For guess-name rooms, this command
349 will work transparently, adding the room to the user's known room list when
350 it completes. For passworded rooms, access will be denied if the password
351 is not supplied or is incorrect, or the command will complete successfully
352 if the password is correct.
354 The possible result codes are:
356 OK - The command completed successfully. User is now in the room.
357 (See the list of returned parameters below)
359 ERROR - The command did not complete successfully. Check the second and
360 third positions of the result code to find out what happened:
362 NOT_LOGGED_IN - Of course you can't go there. You didn't log in.
363 PASSWORD_REQUIRED - Either a password was not supplied, or the supplied
364 password was incorrect.
365 NO_SUCH_ROOM - The requested room does not exist.
367 The typical procedure for entering a passworded room would be:
369 1. Execute a GOTO command without supplying any password.
370 2. ERROR+PASSWORD_REQUIRED will be returned. The client now knows that
371 the room is passworded, and prompts the user for a password.
372 3. Execute a GOTO command, supplying both the room name and the password.
373 4. If OK is returned, the command is complete. If, however,
374 ERROR+PASSWORD_REQUIRED is still returned, tell the user that the supplied
375 password was incorrect. The user remains in the room he/she was previously
378 When the command succeeds, these parameters are returned:
379 0. The name of the room
380 1. Number of unread messages in this room
381 2. Total number of messages in this room
382 3. Info flag: set to nonzero if the user needs to read this room's info
383 file (see RINF command below)
384 4. Various flags associated with this room. (See LKRN cmd above)
385 5. The highest message number present in this room
386 6. The highest message number the user has read in this room
387 7. Boolean flag: 1 if this is a Mail> room, 0 otherwise.
388 8. Aide flag: 1 if the user is either the Room Aide for this room, *or* is
389 a regular Aide (this makes access checks easy).
391 ...and in server 4.01 and above:
392 9. The number of new Mail messages the user has (useful for alerting the
393 user to the arrival of new mail during a session)
395 ...and in server 4.03 and above:
396 10. The floor number this room resides on
399 MSGS (get pointers to MeSsaGeS in this room)
401 This command obtains a listing of all the messages in the current room
402 which the client may request. This command may be passed a single parameter:
403 either "all", "old", or "new" to request all messages, only old messages, or
404 new messages. Or it may be passed two parameters: "last" plus a number, in which
405 case that many message pointers will be returned, or "first" plus a number, for
406 the corresponding effect. If no parameters are specified, "all" is assumed.
408 In Citadel/UX 5.00 and above, the client may also specify "gt" plus a number, to
409 list all messages in the current room with a message number greater than the one
412 This command can return two possible results. An ERROR code may be returned
413 if no user is currently logged in or if something else went wrong. Otherwise,
414 LISTING_FOLLOWS will be returned, and the listing will consist of zero or
415 more message numbers, one per line. The listing ends, as always, with the
416 string "000" alone on a line by itself. The listed message numbers can be used
417 to request messages from the system.
420 MSG0 (read MeSsaGe, mode 0)
422 This is a command used to read the text of a message. "Mode 0" implies that
423 other MSG commands (MSG1, MSG2, etc.) will probably be added later on to read
424 messages in more robust formats. This command should be passed two arguments.
425 The first is the message number of the message being requested. In server
426 version 4.04 and above, the second argument may be set to either 0 to read the
427 entire message, or 1 to read the headers only.
429 The server should, of course, make sure that the client actually has access
430 to the message being requested before honoring this request. Citadel/UX does
431 so by checking the message number against the contents of the current room. If
432 it's not there, the request is denied.
434 If the request is denied, an ERROR code will be returned. Otherwise, the
435 LISTING_FOLLOWS code will be returned, followed by the contents of the message.
436 The following fields may be sent:
438 type= Formatting type. Currently, there are two defined types. Type 0 is
439 "traditional" Citadel formatting. This means that newlines should be treated
440 as spaces UNLESS the first character on the next line is a space. In other
441 words, only indented lines should generate a newline on the user's screen when
442 the message is being displayed. This allows a message to be formatted to the
443 reader's screen width. It also allows the use of proportional fonts.
444 Type 1 is a simple fixed-format message. The message should be displayed to
445 the user's screen as is, preferably in a fixed-width font that will fit 80
448 msgn= The message ID of this message on the system it originated on.
449 path= An e-mailable path back to the user who wrote the message.
451 time= The date and time of the message, in Unix format (the number of
452 seconds since midnight on January 1, 1970, GMT).
454 from= The name of the author of the message.
455 rcpt= If the message is a private e-mail, this is the recipient.
456 room= The name of the room the message originated in.
457 node= The short node name of the system this message originated on.
458 hnod= The long node name of the system this message originated on.
460 text Note that there is no "=" after the word "text". This string
461 signifies that the message text begins on the next line.
464 WHOK (WHO Knows room)
466 This command is available only to Aides. ERROR+HIGHER_ACCESS_REQUIRED will
467 be returned if the user is not an Aide. Otherwise, it returns
468 LISTING_FOLLOWS and then lists, one user per line, every user who has
469 access to the current room.
472 INFO (get server INFO)
474 This command will *always* return LISTING_FOLLOWS and then print out a
475 listing of zero or more strings. Client software should be written to expect
476 anywhere from a null listing to an infinite number of lines, to allow later
477 backward compatibility. The current implementation defines the following
478 parts of the listing:
480 Line 1 - Your unique session ID on the server
481 Line 2 - The node name of the server BBS
482 Line 3 - Human-readable node name of the server BBS
483 Line 4 - The fully-qualified domain name (FQDN) of the server
484 Line 5 - The name of the server software, i.e. "Citadel/UX 4.00"
485 Line 6 - (The revision level of the server code) * 100
486 Line 7 - The geographical location of the BBS (for USA: city and state)
487 Line 8 - The name of the system administrator
488 Line 9 - A number identifying the server type (see below)
489 Line 10 - The text of the system's paginator prompt
491 (version 4.01 and above only)
492 Line 11 - Floor Flag. 1 if the system supports floors, 0 otherwise.
494 *** NOTE! *** The "server type" code is intended to promote global
495 compatibility in a scenario in which developers have added proprietary
496 features to their servers or clients. We are attempting to avoid a future
497 situation in which users need to keep different client software around for
498 each BBS they use. *Please*, if you are a developer and plan to add
499 proprietary features:
501 -> Your client programs should still be able to utilize servers other than
503 -> Clients other than your own should still be able to utilize your server,
504 even if your proprietary extensions aren't supported.
505 -> Please contact Art Cancro <ajc@uncnsrd.mt-kisco.ny.us> and obtain a unique
506 server type code, which can be assigned to your server program.
507 -> If you document what you did in detail, perhaps it can be added to a
508 future release of the Citadel/UX program, so everyone can enjoy it.
510 If everyone follows this scheme, we can avoid a chaotic situation with lots
511 of confusion about which client program works with which server, etc. Client
512 software can simply check the server type (and perhaps the revision level)
513 to determine ahead of time what commands may be utilized. The server type
514 codes currently defined are:
517 ---- ---------------------------------------
518 0 Art Cancro <ajc@uncnsrd.mt-kisco.ny.us>
519 1 Brian Ledbetter <brian@amaranth.com>
520 2 Matthew Scott <gldnspud@telcomplus.com>
521 3 Jesse Vincent <jrvincent@wesleyan.edu>
522 4 Brian Costello <btx@calyx.net>
523 5 Robert Abatecola <robert@tsgus.com>
527 RDIR (Read room DIRectory)
529 Use this command to read the directory of a directory room. ERROR+NOT_HERE
530 will be returned if the room has no directory, or some other error; ERROR +
531 HIGHER_ACCESS_REQUIRED will be returned if the room's directory is not
532 visible and the user does not have Aide or Room Aide privileges; otherwise
533 LISTING_FOLLOWS will be returned, followed by the room's directory. Each
534 line of the directory listing will contain three fields: a filename, the
535 length of the file, and a description.
537 The server message contained on the same line with LISTING_FOLLOWS will
538 contain the name of the system and the name of the directory, such as:
539 uncnsrd.mt-kisco.ny.us|/usr/bbs/files/my_room_directory
542 SLRP (Set Last-message-Read Pointer)
544 This command is used to mark messages as having been read. Its sole parameter
545 is the number of the last message that has been read. This allows the pointer
546 to be set at any arbitrary point in the room. Optionally, the parameter
547 "highest" may be used instead of a message number, to set the pointer to the
548 number of the highest message in the room, effectively marking all messages
549 in the room as having been read (ala the Citadel <G>oto command).
551 The command will return OK if the pointer was set, or ERROR if something
552 went wrong. If OK is returned, it will be followed by a single argument
553 containing the message number the last-read-pointer was set to.
556 INVT (INViTe a user to a room)
558 This command may only be executed by Aides, or by the room aide for the
559 current room. It is used primarily to add users to invitation-only rooms,
560 but it may also be used in other types of private rooms as well. Its sole
561 parameter is the name of the user to invite.
563 The command will return OK if the operation succeeded, or ERROR if it did
564 not. ERROR+HIGHER_ACCESS_REQUIRED may also be returned if the operation
565 would have been possible if the user had higher access, and ERROR+NOT_HERE
566 may be returned if the room is not a private room.
569 KICK (KICK a user out of a room)
571 This is the opposite of INVT: it is used to kick a user out of a private
572 room. It can also be used to kick a user out of a public room, but the
573 effect will only be the same as if the user <Z>apped the room - a non-stupid
574 user can simply un-zap the room to get back in.
577 GETR (GET Room attributes)
579 This command is used for editing the various attributes associated with a
580 room. A typical "edit room" command would work like this:
581 1. Use the GETR command to get the current attributes
582 2. Change some of them around
583 3. Use SETR (see below) to save the changes
584 4. Possibly also change the room aide using the GETA and SETA commands
586 GETR takes no arguments. It will only return OK if the SETR command will
587 also return OK. This allows client software to tell the user that he/she
588 can't edit the room *before* going through the trouble of actually doing the
589 editing. Possible return codes are:
591 ERROR+NOT_LOGGED_IN - No user is logged in.
592 ERROR+HIGHER_ACCESS_REQUIRED - Not enough access. Typically, only aides
593 and the room aide associated with the current room, can access this command.
594 ERROR+NOT_HERE - Lobby>, Mail>, and Aide> cannot be edited.
595 OK - Command succeeded. Parameters are returned.
597 If OK is returned, the following parameters will be returned as well:
599 0. The name of the room
600 1. The room's password (if it's a passworded room)
601 2. The name of the room's directory (if it's a directory room)
602 3. Various flags (bits) associated with the room (see LKRN cmd above)
604 (And on server version 4.01 and above ... )
605 4. The floor number on which the room resides
608 SETR (SET Room attributes)
610 This command sets various attributes associated with the current room. It
611 should be passed the following arguments:
613 0. The name of the room
614 1. The room's password (if it's a passworded room)
615 2. The name of the room's directory (if it's a directory room)
616 3. Various flags (bits) associated with the room (see LKRN cmd above)
617 4. "Bump" flag (see below)
619 (And on server version 4.01 and above, the client may also send ... )
620 5. The floor number on which the room should reside
622 *Important: You should always use GETR to retrieve the current attributes of
623 the room, then change what you want to change, and then use SETR to write it
624 all back. This is particularly important with respect to the flags: if a
625 particular bit is set, and you don't know what it means, LEAVE IT ALONE and
626 only toggle the bits you want to toggle. This will allow for upward
629 If the room is a private room, you have the option of causing all users who
630 currently have access, to forget the room. If you want to do this, set the
631 "bump" flag to 1, otherwise set it to 0.
636 This command is used to get the name of the Room Aide for the current room.
637 It will return ERROR+NOT_LOGGED_IN if no user is logged in, ERROR if there
638 is no current room, or OK if the command succeeded. Along with OK there will
639 be returned one parameter: the name of the Room Aide.
644 The opposite of GETA, used to set the Room Aide for the current room. One
645 parameter should be passed, which is the name of the user who is to be the
646 new Room Aide. Under Citadel/UX, this command may only be executed by Aides
647 and by the *current* Room Aide for the room. Return codes possible are:
648 ERROR+NOT_LOGGED_IN (Not logged in.)
649 ERROR+HIGHER_ACCESS_REQUIRED (Higher access required.)
650 ERROR+NOT_HERE (No current room, or room cannot be edited.
651 Under Citadel/UX, the Lobby> Mail> and Aide> rooms are non-editable.)
652 OK (Command succeeded.)
655 ENT0 (ENTer message, mode 0)
657 This command is used to enter messages into the system. It accepts four
660 0 - Post flag. This should be set to 1 to post a message. If it is
661 set to 0, the server only returns OK or ERROR (plus any flags describing
662 the error) without reading in a message. Client software should, in fact,
663 perform this operation at the beginning of an "enter message" command
664 *before* starting up its editor, so the user does not end up typing a message
665 in vain that will not be permitted to be saved. If it is set to 2, the
666 server will accept an "apparant" post name if the user is privileged enough.
667 This post name is arg 4.
668 1 - Recipient. This argument is utilized only for private mail messages.
669 It is ignored for public messages. It contains, of course, the name of the
670 recipient of the message.
671 2 - Anonymous flag. This argument is ignored unless the room allows
672 anonymous messages. In such rooms, this flag may be set to 1 to flag a
673 message as anonymous, otherwise 0 for a normal message.
674 3 - Format type. Any valid Citadel/UX format type may be used (this will
675 typically be 0; see the MSG0 command above).
676 4 - Post name. When postflag is 2, this is the name you are posting as.
677 This is an Aide only command.
679 Possible result codes:
680 OK - The request is valid. (Client did not set the "post" flag, so the
681 server will not read in message text.) If the message is an e-mail with
682 a recipient, the text that follows the OK code will contain the exact name
683 to which mail is being sent. The client can display this to the user. The
684 implication here is that the name that the server returns will contain the
685 correct upper and lower case characters. In addition, if the recipient is
686 having his/her mail forwarded, the forwarding address will be returned.
687 SEND_LISTING - The request is valid. The client should now transmit
688 the text of the message (ending with a 000 on a line by itself, as usual).
689 ERROR - Miscellaneous error. (Explanation probably follows.)
690 ERROR + NOT_LOGGED_IN - Not logged in.
691 ERROR + HIGHER_ACCESS_REQUIRED - Higher access is required. An
692 explanation follows, worded in a form that can be displayed to the user.
693 ERROR + NO_SUCH_USER - The specified recipient does not exist.
696 RINF (read Room INFormation file)
698 Each room has associated with it a text file containing a description of
699 the room, perhaps containing its intended purpose or other important
700 information. The info file for the Lobby> (the system's base room) is
701 often used as a repository for system bulletins and the like.
703 This command, which accepts no arguments, is simply used to read the info
704 file for the current room. It will return LISTING_FOLLOWS followed by
705 the text of the message (always in format type 0) if the request can be
706 honored, or ERROR if no info file exists for the current room (which is
707 often the case). Other error description codes may accompany this result.
709 When should this command be used? This is, of course, up to the discretion
710 of client software authors, but in Citadel it is executed in two situations:
711 the first time the user ever enters a room; and whenever the contents of the
712 file change. The latter can be determined from the result of a GOTO command,
713 which will tell the client whether the file needs to be read (see GOTO above).
716 DELE (DELEte a message)
718 Delete a message from the current room. The one argument that should be
719 passed to this command is the message number of the message to be deleted.
720 The return value will be OK if the message was deleted, or an ERROR code.
723 MOVE (MOVE a message to a different room)
725 Move a message to a different room. The two arguments that should be passed
726 to this command are the message number of the message to be deleted, and the
727 name of the target room. If the operation succeeds, the message will be
728 deleted from the current room and moved to the target room. An ERROR code
729 usually means that either the user does not have permission to perform this
730 operation, or that the target room does not exist.
733 KILL (KILL current room)
735 This command deletes the current room. It accepts a single argument, which
736 should be nonzero to actually delete the room, or zero to merely check
737 whether the room can be deleted.
739 Once the room is deleted, the current room is undefined. It is suggested
740 that client software immediately GOTO another room (usually _BASEROOM_)
741 after this command completes.
743 Possible return codes:
745 OK - room has been deleted (or, if checking only, request is valid).
746 ERROR+NOT_LOGGED_IN - no user is logged in.
747 ERROR+HIGHER_ACCESS_REQUIRED - not enough access to delete rooms.
748 ERROR+NOT_HERE - this room can not be deleted.
751 CRE8 (CRE[ate] a new room)
753 This command is used to create a new room. Like some of the other
754 commands, it provides a mechanism to first check to see if a room can be
755 created before actually executing the command. CRE8 accepts the following
758 0 - Create flag. Set this to 1 to actually create the room. If it is
759 set to 0, the server merely checks that there is a free slot in which to
760 create a new room, and that the user has enough access to create a room. It
761 returns OK if the client should go ahead and prompt the user for more info,
762 or ERROR or ERROR+HIGHER_ACCESS_REQUIRED if the command will not succeed.
763 1 - Name for new room.
764 2 - Access type for new room:
766 1 - Private; can be entered by guessing the room's name
767 2 - Private; can be entered by knowing the name *and* password
768 3 - Private; invitation only (sometimes called "exclusive")
769 3 - Password for new room (if it is a type 2 room)
770 4 - Floor number on which the room should reside (optional, and in server
771 version 4.01 and above only)
773 If the create flag is set to 1, the room is created (unless something
774 went wrong and an ERROR return is sent), and the server returns OK, but
775 the session is **not** automatically sent to that room. The client still
776 must perform a GOTO command to go to the new room.
779 FORG (FORGet the current room)
781 This command is used to forget (zap) the current room. For those not
782 familiar with Citadel, this terminology refers to removing the room from
783 a user's own known rooms list, *not* removing the room itself. After a
784 room is forgotten, it no longer shows up in the user's known room list,
785 but it will exist in the user's forgotten room list, and will return to the
786 known room list if the user goes to the room (in Citadel, this is
787 accomplished by explicitly typing the room's name in a <.G>oto command).
789 The command takes no arguments. If the command cannot execute for any
790 reason, ERROR will be returned. ERROR+NOT_LOGGED_IN or ERROR+NOT_HERE may
791 be returned as they apply.
793 If the command succeeds, OK will be returned. At this point, the current
794 room is **undefined**, and the client software is responsible for taking
795 the user to another room before executing any other room commands (usually
796 this will be _BASEROOM_ since it is always there).
799 MESG (read system MESsaGe)
801 This command is used to display system messages and/or help files. The
802 single argument it accepts is the name of the file to display. IT IS CASE
803 SENSITIVE. Citadel/UX looks for these files first in the "messages"
804 subdirectory and then in the "help" subdirectory.
806 If the file is found, LISTING_FOLLOWS is returned, followed by a pathname
807 to the file being displayed. Then the message is printed, in format type 0
808 (see MSG0 command for more information on this). If the file is not found,
811 There are some "well known" names of system messages which client software
812 may expect most servers to carry:
814 hello - Welcome message, to be displayed before the user logs in.
815 changepw - To be displayed whenever the user is prompted for a new
816 password. Warns about picking guessable passwords and such.
817 register - Should be displayed prior to the user entering registration.
818 Warnings about not getting access if not registered, etc.
819 help - Main system help file.
820 goodbye - System logoff banner; display when user logs off.
821 roomaccess - Information about how public rooms and different types of
822 private rooms function with regards to access.
823 unlisted - Tells users not to choose to be unlisted unless they're
824 really paranoid, and warns that aides can still see
825 unlisted userlog entries.
827 Citadel/UX provides these for the Citadel/UX Unix text client. They are
828 probably not very useful for other clients:
830 mainmenu - Main menu (when in idiot mode).
835 saveopt - Options to save a message, abort, etc.
836 entermsg - Displayed just before a message is entered, when in
840 GNUR (Get Next Unvalidated User)
842 This command shows the name of a user that needs to be validated. If there
843 are no unvalidated users, OK is returned. Otherwise, MORE_DATA is returned
844 along with the name of the first unvalidated user the server finds. All of
845 the usual ERROR codes may be returned as well (for example, if the user is
846 not an Aide and cannot validate users).
848 A typical "Validate New Users" command would keep executing this command,
849 and then validating each user it returns, until it returns OK when all new
850 users have been validated.
853 GREG (Get REGistration for user)
855 This command retrieves the registration info for a user, whose name is the
856 command's sole argument. All the usual error messages can be returned. If
857 the command succeeds, LISTING_FOLLOWS is returned, followed by the user's name
858 (retrieved from the userlog, with the right upper and lower case etc.) The
859 contents of the listing contains one field per line, followed by the usual
860 000 on the last line.
862 The following lines are defined. Others WILL be added in the futre, so all
863 software should be written to read the lines it knows about and then ignore
869 Line 4: Street address or PO Box
870 Line 5: City/town/village/etc.
871 Line 6: State/province/etc.
873 Line 8: Telephone number
875 Line 10: Internet e-mail address
877 Users without Aide privileges may retrieve their own registration using
878 this command. This can be accomplished either by passing the user's own
879 name as the argument, or the string "_SELF_". The command will always
880 succeed when used in this manner, unless no user is logged in.
885 This command is used to validate users. Obviously, it can only be executed
886 by users with Aide level access. It should be passed two parameters: the
887 name of the user to validate, and the desired access level
889 If the command succeeds, OK is returned. The user's access level is changed
890 and the "need validation" bit is cleared. If the command fails for any
891 reason, ERROR, ERROR+NO_SUCH_USER, or ERROR+HIGHER_ACCESS_REQUIRED will be
895 EINF (Enter INFo file for room)
897 Transmit the info file for the current room with this command. EINF uses
898 a boolean flag (1 or 0 as the first and only argument to the command) to
899 determine whether the client actually wishes to transmit a new info file, or
900 is merely checking to see if it has permission to do so.
902 If the command cannot succeed, it returns ERROR.
903 If the client is only checking for permission, and permission will be
904 granted, OK is returned.
905 If the client wishes to transmit the new info file, SEND_LISTING is
906 returned, and the client should transmit the text of the info file, ended
907 by the usual 000 on a line by itself.
912 This is a simple user listing. It always succeeds, returning
913 LISTING_FOLLOWS followed by zero or more user records, 000 terminated. The
914 fields on each line are as follows:
919 4. Date/time of last login (Unix format)
922 7. Password (listed only if the user requesting the list is an Aide)
924 Unlisted entries will also be listed to Aides logged into the server, but
925 not to ordinary users.
928 REGI (send REGIstration)
930 Clients will use this command to transmit a user's registration info. If
931 no user is logged in, ERROR+NOT_LOGGED_IN is returned. Otherwise,
932 SEND_LISTING is returned, and the server will expect the following information
933 (terminated by 000 on a line by itself):
936 Line 2: Street address or PO Box
937 Line 3: City/town/village/etc.
938 Line 4: State/province/etc.
940 Line 6: Telephone number
941 Line 7: e-mail address
944 CHEK (CHEcK various things)
946 When logging in, there are various things that need to be checked. This
947 command will return ERROR+NOT_LOGGED_IN if no user is logged in. Otherwise
948 it returns OK and the following parameters:
950 0: Number of new private messages in Mail>
951 1: Nonzero if the user needs to register
952 2: (Relevant to Aides only) Nonzero if new users require validation
957 This command deletes a file from the room's directory, if there is one. The
958 name of the file to delete is the only parameter to be supplied. Wildcards
959 are not acceptable, and any slashes in the filename will be converted to
960 underscores, to prevent unauthorized access to neighboring directories. The
961 possible return codes are:
963 OK - Command succeeded. The file was deleted.
964 ERROR+NOT_LOGGED_IN - Not logged in.
965 ERROR+HIGHER_ACCESS_REQUIRED - Not an Aide or Room Aide.
966 ERROR+NOT_HERE - There is no directory in this room.
967 ERROR+FILE_NOT_FOUND - Requested file was not found.
972 This command is similar to DELF, except that it moves a file (and its
973 associated file description) to another room. It should be passed two
974 parameters: the name of the file to move, and the name of the room to move
975 the file to. All of the same return codes as DELF may be returned, and also
976 one additional one: ERROR+NO_SUCH_ROOM, which means that the target room
977 does not exist. ERROR+NOT_HERE could also mean that the target room does
978 not have a directory.
981 NETF (NETwork send a File)
983 This command is similar to MOVF, except that it attempts to send a file over
984 the network to another system. It should be passed two parameters: the name
985 of the file to send, and the node name of the system to send it to. All of
986 the same return codes as MOVF may be returned, except for ERROR+NO_SUCH_ROOM.
987 Instead, ERROR+NO_SUCH_SYSTEM may be returned if the name of the target
990 The name of the originating room will be sent along with the file. Most
991 implementations will look for a room with the same name at the receiving end
992 and attempt to place the file there, otherwise it goes into a bit bucket room
993 for miscellaneous files. This is, however, beyond the scope of this document;
994 see elsewhere for more details.
997 RWHO (Read WHO's online)
999 Displays a list of all users connected to the server. No error codes are
1000 ever returned. LISTING_FOLLOWS will be returned, followed by zero or more
1001 lines containing the following three fields:
1003 0 - Session ID. Citadel/UX fills this with the pid of a server program.
1005 2 - The name of the room the user is currently in. This field might not
1006 be displayed (for example, if the user is in a private room) or it might
1007 contain other information (such as the name of a file the user is
1009 3 - (server v4.03 and above) The name of the host the client is connecting
1010 from, or "localhost" if the client is local.
1011 4 - (server v4.04 and above) Description of the client software being used
1012 5 - The last time, locally to the server, that a command was received from
1013 this client (Note: NOOP's don't count)
1014 6 - The last command received from a client. (NOOP's don't count)
1015 7 - Session flags. These are: + (spoofed address), - (STEALTH mode), *
1016 (posting) and . (idle).
1018 The listing is terminated, as always, with the string "000" on a line by
1022 OPEN (OPEN a file for download)
1024 This command is used to open a file for downloading. Only one download
1025 file may be open at a time. The only argument to this command is the name
1026 of the file to be opened. The user should already be in the room where the
1027 file resides. Possible return codes are:
1030 ERROR+NOT_HERE (no directory in this room)
1031 ERROR+FILE_NOT_FOUND (could not open the file)
1035 If the file is successfully opened, OK will be returned, along with the
1036 size (in bytes) of the file, and (in version 5.00 and above) the time of last
1040 CLOS (CLOSe the download file)
1042 This command is used to close the download file. It returns OK if the
1043 file was successfully closed, or ERROR if there wasn't any file open in the
1047 READ (READ from the download file)
1049 Two arguments are passed to this command. The first is the starting position
1050 in the download file, and the second is the total number of bytes to be
1051 read. If the operation can be performed, BINARY_FOLLOWS will be returned,
1052 along with the number of bytes to follow. Then, immediately following the
1053 newline, will be that many bytes of binary data. The client *must* read
1054 exactly that number of bytes, otherwise the client and server will get out
1057 If the operation cannot be performed, any of the usual error codes will be
1061 UOPN (OPeN a file for Uploading)
1063 This command is similar to OPEN, except that this one is used when the
1064 client wishes to upload a file to the server. The first argument is the name
1065 of the file to create, and the second argument is a one-line comment
1066 describing the contents of the file. Only one upload file may be open at a
1067 time. Possible return codes are:
1070 ERROR+NOT_HERE (no directory in this room)
1071 ERROR+FILE_NOT_FOUND (a name must be specified)
1072 ERROR (miscellaneous errors)
1073 ERROR+ALREADY_EXISTS (a file with the same name already exists)
1076 If OK is returned, the command has succeeded and writes may be performed.
1079 UCLS (CLoSe the Upload file)
1081 Close the file opened with UOPN. An argument of "1" should be passed to
1082 this command to close and save the file; otherwise, the transfer will be
1083 considered aborted and the file will be deleted. This command returns OK
1084 if the operation succeeded or ERROR if it did not.
1087 WRIT (WRITe to the upload file)
1089 If an upload file is open, this command may be used to write to it. The
1090 argument passed to this command is the number of bytes the client wishes to
1091 transmit. An ERROR code will be returned if the operation cannot be
1094 If the operation can be performed, SEND_BINARY will be returned, followed
1095 by the number of bytes the server is expecting. The client must then transmit
1096 exactly that number of bytes. Note that in the current implementation, the
1097 number of bytes the server is expecting will always be the number of bytes
1098 the client requested to transmit, but the client software should never assume
1099 that this will always happen, in case changes are made later.
1102 QUSR (Query for a USeR)
1104 This command is used to check to see if a particular user exists. The only
1105 argument to this command is the name of the user being searched for. If
1106 the user exists, OK is returned, along with the name of the user in the userlog
1107 (so the client software can learn the correct upper/lower casing of the name
1108 if necessary). If the user does not exist, ERROR+NO_SUCH_USER is returned.
1109 No login or current room is required to utilize this command.
1112 OIMG (Open an IMaGe file)
1114 Open an image (graphics) file for downloading. Once opened, the file can be
1115 read as if it were a download file. This implies that an image and a download
1116 cannot be opened at the same time. OIMG returns the same result codes as OPEN.
1118 All images will be in GIF (Graphics Interchange Format). In the case of
1119 Citadel/UX, the server will convert the supplied filename to all lower case,
1120 append the characters ".gif" to the filename, and look for it in the "images"
1121 subdirectory. As with the MESG command, there are several "well known"
1122 images which are likely to exist on most servers:
1124 hello - "Welcome" graphics to be displayed alongside MESG "hello"
1125 goodbye - Logoff banner graphics to be displayed alongside MESG "goodbye"
1126 background - Background image (usually tiled) for graphical clients
1128 The following "special" image names are defined in Citadel/UX server version
1131 _userpic_ - Picture of a user (send the username as the second argument)
1132 _floorpic_ - A graphical floor label (send the floor number as the second
1133 argument). Clients which request a floor picture will display
1134 the picture *instead* of the floor name.
1135 _roompic_ - A graphic associated with the *current* room. Clients which
1136 request a room picture will display the picture in *addition*
1137 to the room name (i.e. it's used for a room banner, as
1138 opposed to the floor picture's use in a floor listing).
1142 ---------------------------------------------------------------------------
1143 The following commands are available only in Citadel/UX server version 4.01
1145 ---------------------------------------------------------------------------
1147 NETP (authenticate as network session with system NET Password)
1149 This command is used by client software to identify itself as a transport
1150 session for IGnet/Open BBS to BBS networking. It should be called with
1151 two arguments: the node name of the calling system, and the system net
1152 password for the server. If the authentication succeeds, NETP will return
1153 OK, otherwise, it returns ERROR.
1156 NUOP (Network Upload OPen file)
1158 Open a network spool file for uploading. The client must have already
1159 identified itself as a network session using the NETP command. If the command
1160 returns OK, the client may begin transmitting IGnet/Open spool data using
1161 a series of WRIT commands. When a UCLS command is issued, the spooled data
1162 is entered into the BBS if the argument to UCLS is 1 or discarded if the
1163 argument to UCLS is 0. If the client has not authenticated itself with a
1164 NETP command, ERROR+HIGHER_ACCESS_REQUIRED will be returned.
1167 NDOP (Network Download OPen file)
1169 Open a network spool file for downloading. The client must have already
1170 identified itself as a network session using the NETP command. If the command
1171 returns OK, the client may begin receiving IGnet/Open spool data using
1172 a series of READ commands. When a CLOS command is issued, the spooled data
1173 is deleted from the server and may not be read again. If the client has not
1174 authenticated itself with a NETP command, ERROR+HIGHER_ACCESS_REQUIRED will
1178 LFLR (List all known FLooRs)
1180 On systems supporting floors, this command lists all known floors. The
1181 command accepts no parameters. It will return ERROR+NOT_LOGGED_IN if no
1182 user is logged in. Otherwise it returns LISTING_FOLLOWS and a list of
1183 the available floors, each line consisting of three fields:
1185 1. The floor number associated with the floor
1186 2. The name of the floor
1187 3. Reference count (number of rooms on this floor)
1190 CFLR (Create a new FLooR)
1192 This command is used to create a new floor. It should be passed two
1193 arguments: the name of the new floor to be created, and a 1 or 0 depending
1194 on whether the client is actually creating a floor or merely checking to
1195 see if it has permission to create the floor. The user must be logged in
1196 and have Aide privileges to create a floor.
1198 If the command succeeds, it will return OK followed by the floor number
1199 associated with the new floor. Otherwise, it will return ERROR (plus perhaps
1200 HIGHER_ACCESS_REQUIRED, ALREADY_EXISTS, or INVALID_FLOOR_OPERATION)
1201 followed by a description of why the command failed.
1206 This command is used to delete a floor. It should be passed two
1207 argument: the *number* of the floor to be deleted, and a 1 or 0 depending
1208 on whether the client is actually deleting the floor or merely checking to
1209 see if it has permission to delete the floor. The user must be logged in
1210 and have Aide privileges to delete a floor.
1212 Floors that contain rooms may not be deleted. If there are rooms on a floor,
1213 they must be either deleted or moved to different floors first. This implies
1214 that the Main Floor (floor 0) can never be deleted, since Lobby>, Mail>, and
1215 Aide> all reside on the Main Floor and cannot be deleted.
1217 If the command succeeds, it will return OK. Otherwise it will return
1218 ERROR (plus perhaps HIGHER_ACCESS_REQUIRED or INVALID_FLOOR_OPERATION)
1219 followed by a description of why the command failed.
1224 Edit the parameters of a floor. The client may pass one or more parameters
1227 1. The number of the floor to be edited
1228 2. The desired new name
1230 More parameters may be added in the future. Any parameters not passed to
1231 the server will remain unchanged. A minimal command would be EFLR and a
1232 floor number -- which would do nothing. EFLR plus the floor number plus a
1233 floor name would change the floor's name.
1235 If the command succeeds, it will return OK. Otherwise it will return
1236 ERROR (plus perhaps HIGHER_ACCESS_REQUIRED or INVALID_FLOOR_OPERATION)
1238 ---------------------------------------------------------------------------
1239 The following commands are available only in Citadel/UX server version 4.02
1241 ---------------------------------------------------------------------------
1243 IDEN (IDENtify the client software)
1245 The client software has the option to identify itself to the server.
1246 Currently, the server does nothing with this information except to write
1247 it to the syslog to satisfy the system administrator's curiosity. Other
1248 uses might become apparent in the future.
1250 The IDEN command should contain five fields: a developer ID number (same as
1251 the server developer ID numbers in the INFO command -- please obtain one if
1252 you are a new developer), a client ID number (which does not have to be
1253 globally unique - only unique within the domain of the developer number),
1254 a version number, a free-form text string describing the client, and the name
1255 of the host the user is located at.
1257 It is up to the server to determine whether to accept the host name or to
1258 use the host name it has detected itself. Generally, if the client is
1259 running on a trusted host (either localhost or a well-known publically
1260 accessible client) it should use the host name transmitted by IDEN,
1261 otherwise it should use the host name it has detected itself.
1263 IDEN always returns OK, but since that's the only way it ever returns
1264 there's no point in checking the result code.
1266 ---------------------------------------------------------------------------
1267 The following commands are available only in Citadel/UX server version 4.03
1269 ---------------------------------------------------------------------------
1271 IPGM (identify as an Internal ProGraM)
1273 IPGM is a low-level command that should not be used by normal user clients.
1274 It is used for various utilities to communicate with the server on the same
1275 host. For example, the networker (netproc.c) logs onto the server as an
1276 internal program in order to fetch and store messages. Since user clients
1277 do not utilize this command (or any of its companion commands), developers
1278 writing Citadel-compatible servers need not implement it.
1280 The sole argument to IPGM is the system's internal program password. This
1281 password is generated by the setup program and stored in the config file.
1282 Since internal programs have access to the config file, they know the correct
1285 IPGM returns OK for a correct authentication or ERROR otherwise.
1288 CHAT (enter CHAT mode)
1290 This command functions differently from every other command in the system. It
1291 is used to implement multi-user chat. For this to function, a new transfer
1292 mode, called START_CHAT_MODE, is implemented. If a client does not support
1293 chat mode, it should never send a CHAT command!
1295 In chat mode, messages may arrive asynchronously from the server at any
1296 time. The client may send messages at any time. This allows the arrival of
1297 messages without the client having to poll for them. Arriving messages will
1298 be of the form "user|message", where the "user" portion is, of course, the
1299 name of the user sending the message, and "message" is the message text.
1301 Chat mode ends when the server says it ends. The server will signal the end
1302 of chat mode by transmitting "000" on a line by itself. When the client reads
1303 this line, it must immediately exit from chat mode without sending any
1304 further traffic to the server. The next transmission sent to the server
1305 will be a regular server command.
1307 The Citadel/UX server understands the following commands:
1308 /quit - Exit from chat mode (causes the server to do an 000 end)
1309 /who - List users currently in chat
1310 /whobbs - List users currently in chat and on the bbs
1311 /me - Do an irc-style action.
1312 /join - Join a new "room" in which all messages are only heard by
1313 people in that room.
1314 /msg - /msg <user> <msg> will send the msg to <user> only.
1315 /help - Print help information
1316 NOOP - Do nothing (silently)
1318 Any other non-empty string is treated as message text and will be broadcast
1319 to other users currently in chat.
1322 SEXP (Send EXPress messages)
1324 This is one of two commands which implement "express messages" (also known
1325 as "paging"). An express message is a near-real-time message sent from one
1326 logged in user to another. When an express message is sent, it will be
1327 displayed the next time the target user executes a PEXP command.
1329 The SEXP command accepts two arguments: the name of the user to send the
1330 message to, and the text of the message. If the message is successfully
1331 transmitted, OK is returned. If the target user is not logged in or if
1332 anything else goes wrong, ERROR is returned.
1334 In Citadel/UX 5.00 and above, the reserved name "broadcast" may be used
1335 instead of a user name, to broadcast an express message to all users
1336 currently connected to the server.
1338 Do be aware that if an express message is transmitted to a user who is logged
1339 in using a client that does not check for express messages, the message will
1343 PEXP (Print EXPress messages)
1345 This command, called without any arguments, simply dumps out the contents
1346 of any waiting express messages. It returns ERROR if there is a problem,
1347 otherwise it returns LISTING_FOLLOWS followed by all messages.
1349 So how does the client know there are express messages waiting? It could
1350 execute a random PEXP every now and then. Or, it can check the byte in
1351 server return code messages, between the return code and the parameters. In
1352 much the same way as FTP uses "-" to signify a continuation, Citadel uses
1353 an "*" in this position to signify the presence of waiting express messages.
1355 ---------------------------------------------------------------------------
1356 The following commands are available only in Citadel/UX server version 4.10
1358 ---------------------------------------------------------------------------
1360 EBIO (Enter BIOgraphy)
1362 Transmit to the server a free-form text file containing a little bit of
1363 information about the user for other users to browse. This is typically
1364 referred to as a 'bio' online. EBIO returns SEND_LISTING if it succeeds,
1365 after which the client is expected to transmit the file, or any of the usual
1366 ERROR codes if it fails.
1369 RBIO (Read BIOgraphy)
1371 Receive from the server a named user's bio. This command should be passed
1372 a single argument - the name of the user whose bio is requested. RBIO returns
1373 LISTING_FOLLOWS plus the bio file if the user exists and has a bio on file,
1374 ERROR+NO_SUCH_USER if the named user does not exist, or ERROR+FILE_NOT_FOUND
1375 if the user exists but has no bio on file.
1377 ---------------------------------------------------------------------------
1378 The following commands are available only in Citadel/UX server version 4.11
1380 ---------------------------------------------------------------------------
1382 STEL (enter STEaLth mode)
1384 When in "stealth mode," a user will not show up in the "Who is online"
1385 listing (the RWHO server command). Only Aides may use stealth mode. The
1386 STEL command accepts one argument: a 1 indicating that the user wishes to
1387 enter stealth mode, or a 0 indicating that the user wishes to exit stealth
1388 mode. STEL returns OK if the command succeeded, ERROR+NOT_LOGGED_IN if no
1389 user is logged in, or ERROR+HIGHER_ACCESS_REQUIRED if the user is not an Aide.
1391 The STEL command also makes it so a user does not show up in the chat room
1395 LBIO (List users who have BIOs on file)
1397 This command is self-explanatory. Any user who has used EBIO to place a bio
1398 on file is listed. LBIO almost always returns LISTING_FOLLOWS followed by
1399 this listing, unless it experiences an internal error in which case ERROR
1403 MSG2 (read MeSsaGe, mode 2)
1405 MSG2 follows the same calling convention as MSG0. The difference between
1406 the two commands is that MSG2 outputs messages in standard RFC822 format
1407 rather than in Citadel/UX proprietary format.
1409 This command was implemented in order to make various gateway programs
1410 easier to implement, and to provide some sort of multimedia support in the
1411 future. Keep in mind that when this command is used, all messages will be
1412 output in fixed 80-column format.
1414 ---------------------------------------------------------------------------
1415 The following commands are available only in Citadel/UX server version 5.00
1417 ---------------------------------------------------------------------------
1419 MSG3 (read MeSsaGe, mode 3 -- internal command)
1421 MSG3 is for use by internal programs only and should not be utilized by
1422 user-mode clients. It does require IPGM authentication. MSG3 follows the
1423 same calling convention as the other MSG commands, but upon success returns
1424 BINARY_FOLLOWS followed by a data block containing the _raw_ message format
1428 ENT3 (ENTer message, mode 3 -- internal command)
1430 ENT3 is for use by internal programs only and should not be utilized by
1431 user-mode clients. It does require IPGM authentication. This command posts
1432 a raw message straight into the message base without modification or performing
1433 any checks. It accepts the following arguments:
1435 0 - Post flag. This should be set to 1 to post a message. If it is
1436 set to 0, the server only returns OK or ERROR (plus any flags describing
1437 the error) without reading in a message. This is used to verify the operation
1438 before actually transmitting a message.
1439 1 - Recipient. This argument is utilized only for private mail messages.
1440 It is ignored for public messages. It contains, of course, the name of the
1441 recipient of the message.
1442 2 - The size (in bytes) of the message to be transmitted.
1444 ENT3 returns OK to tell the client that a message can be posted, ERROR if
1445 there would be a problem with the operation, or SEND_BINARY followed by a byte
1446 count if it is expecting the message to be transmitted.
1449 TERM (TERMinate another session)
1451 In a multithreaded environment, it sometimes becomes necessary to terminate
1452 a session that is unusable for whatever reason. The TERM command performs
1453 this task. Naturally, only Aides can execute TERM. The command should be
1454 called with a single argument: the session ID (obtained from an RWHO command)
1455 of the session to be terminated.
1457 TERM returns OK if the session was terminated, or ERROR otherwise. Note that
1458 a client program is prohibited from terminating the session it is currently
1462 NSET (Network SETup commands)
1464 Aides may use this command to configure the networker. This command's
1465 parameters are passed directly to the 'netsetup' command line utility. If
1466 netsetup returns a non-zero exit code, ERROR is returned, along with the
1467 error message (if any). If netsetup returns a zero (success) exit code,
1468 LISTING_FOLLOWS is returned, followed by zero or more lines of output (since
1469 netsetup may have information to display, such as a room or node list) and
1470 the usual '000' listing terminator.
1473 DOWN (shut DOWN the server)
1475 This command, which may only be executed by an Aide, immediately shuts down
1476 the server. It is only implemented on servers on which such an operation is
1477 possible, such as a multithreaded Citadel engine. The server does not restart.
1478 DOWN returns OK if the user is allowed to shut down the server, in which case
1479 the client program should expect the connection to be immediately broken.
1482 SCDN (Schedule or Cancel a shutDowN)
1484 SCDN sets or clears the "scheduled shutdown" flag. Pass this command a 1 or
1485 0 to respectively set or clear the flag. When the "scheduled shutdown" flag is
1486 set, the server will be shut down when there are no longer any users logged in.
1487 Any value other than 0 or 1 will not change the flag, only report its state.
1488 No users will be kicked off the system, and in fact the server is still available
1489 for new connections. The command returns ERROR if it fails; otherwise, it
1490 returns OK followed by a number representing the current state of the flag.
1493 EMSG (Enter a system MeSsaGe)
1495 This is the opposite of the MESG command - it allows the creation and editing
1496 of system messages. The only argument passed to EMSG is the name of the
1497 file being transmitted. If the file exists in any system message directory
1498 on the server it will be overwritten, otherwise a new file is created. EMSG
1499 returns SEND_LISTING on success or ERROR+HIGHER_ACCESS_REQUIRED if the user
1502 Typical client software would use MESG to retrieve any existing message into
1503 an edit buffer, then present an editor to the user and run EMSG if the changes
1507 UIMG (Upload an IMaGe file)
1509 UIMG is complemenary to OIMG; it is used to upload an image to the server.
1510 The first parameter supplied to UIMG should be 0 if the client is only checking
1511 for permission to upload, or 1 if the client is actually attempting to begin
1512 the upload operation. The second argument is the name of the file to be
1513 transmitted. In Citadel/UX, the filename is converted to all lower case,
1514 appended with the characters ".gif", and stored in the "images" directory.
1516 UIMG returns OK if the client has permission to perform the requested upload,
1517 or ERROR+HIGHER_ACCESS_REQUIRED otherwise. If the client requested to begin
1518 the operation (first parameter set to 1), an upload file is opened, and the
1519 client should begin writing to it with WRIT commands, then close it with a
1522 The supplied filename should be one of:
1524 -> _userpic_ (Server will attempt to write to the user's online photo)
1525 -> Any of the "well known" filenames described in the writeup for the
1528 ----------------------------------------------
1529 The following are for citserver 5.02 and above
1530 ----------------------------------------------
1532 HCHG (Hostname CHanGe)
1534 HCHG is a command, usable by any user, that allows a user to change their RWHO
1535 host value. This will mask a client's originating hostname from normal
1536 users; access level 6 and higher see an entry right underneath the spoofed
1537 entry listing the actual hostname the user originates from.
1539 The format of an HCHG command is:
1544 If a HCHG command is successful, the value OK (200) is returned.
1546 RCHG (Roomname CHanGe)
1548 RCHG is a command, usable by any user, that allows a user to change their RWHO
1549 room value. This will mask a client's roomname from normal users; access
1550 level 6 and higher see an entry right underneath the spoofed entry listing
1551 the actual room the user is in.
1553 The format of an RCHG command is:
1557 If a RCHG command is successful, the value OK (200) is returned.
1559 UCHG (Username CHanGe)
1561 UCHG is an aide-level command which allows an aide to effectively change their
1562 username. If this value is blank, the user goes into stealth mode (see
1564 will show up as being from the real username in this mode, however. In
1565 addition, the RWHO listing will include both the spoofed and real usernames.
1567 The format of an UCHG command is:
1571 If a UCHG command is successful, the value OK (200) is returned.
1573 TIME (Get server local TIME)
1575 TIME returns a string in the following format:
1579 Where A is OK (200), B is the current time measured in seconds since
1580 00:00:00 GMT, Jan 1, 1970.
1582 This is used in allowing a client to calculate idle times.