MODEMS(2)

NAME
libmodem, dial, ldial, bdial, bldial, close_nohangup, hangup, modems, getmdmnam, setmdms, getnextmdm, mdm_lock, mdm_unlock, mdm_chklock, _mdm_sys_errlist, mdmerrno, mdmstrerror, mdmperror - modem management package.

SYNOPSIS
#include <dial/modems.h>

DESCRIPTION
libmodem.a is a library that allow you to use your modems transparently with regard of kind of modem attached to a line. You have just to int fd;
fd = dial("Some-phone-number"); and it will return to you a file descriptor of the dialed line. To hangup just hangup(fd). Of course, you have to configure all your modem lines in the /etc/modems file to allow the library know which modem lines it can use to dial.

HEADER FILES
<dial/modems.h>
<dial/mdmerrno.h> (included by dial/modems.h)

STRUCTURES

    struct modems {
    	char line[MAXNAMLEN];	/* line name (without /dev/) */
    	char cp[MAXMDMCMD];		/* command prefix */
    	char ce[MAXMDMCMD];		/* command end */
    	char at[MAXMDMCMD];		/* attention string */
    	time_t          dl;		/* delay waiting answer from mdm */
    	int             bd;		/* max baud rate */
    	char cs[MAXMDMCMD];		/* connect string */
    	char ds[MAXMDMCMD];		/* dial string */
    	char de[MAXMDMCMD];		/* dial end */
    	char im[MAXMDMCMD];		/* initialize modem */
    	char hu[MAXMDMCMD];		/* hangup string */
    	int             fc;		/* flow control */
    };

FUNCTIONS AND VARIABLES
/*
 *
 * extern declarations
 * (exported functions and variables from libmodem.a)
 */

modems.c
In the file modems.c there are all the function related with the modem devices database (/etc/modems). ********************************************************************
*
* #include <modems.h>
*
* extern struct modems *getmdmnam(char *device); device is a string containing a modem device (without the prefix /dev/) RETURN VALUES:
a pointer to the modem description structure (NULL on error) The storage of the structure returned is a static area that is rewritten at every invocation of getmdmnam() Eg.: #include <modems.h> struct modems *mdm; mdm = getmdmnam("modem"); ********************************************************************
*
* #include <modems.h>
*
* extern void setmdms(void);
* extern struct modems *getnextmdm(void);
This pair of functions allow you to navigate the /etc/modems file. setmdms() sets up the libmodem for navigation. RETURN VALUES:
getnextmdm() return a pointer to the next modem description in /etc/modems file, NULL on error or no more modems. You can call getnextmdm() more times to get one by one all the modems configured in /etc/modems. The storage of the structure returned is a static area that is rewritten at every invocation of getnextmdm() Eg: #include <modems.h> struct modems *mdm; setmdms(); while ((mdm = getnextmdm()) != NULL) {
    /* do something */
}

line_manage.c
In line_manage.c are all the functions related to the work of modems. dial a number, talk to modem, etc. ********************************************************************
*
* #include <modems.h>
*
* extern int dial(char *phone);
* extern int ldial(char *phone, char *line);
* extern int bdial(char *phone, int speed);
* extern int bldial(char *phone, char *line, int speed);
* extern int close_nohangup(int fd);
* extern int hangup(int fd); (bl)dial() are all functions that dial a phone number over a modem line. phone is a string containing the phone number to be dialed. It is mandatory if you want to dial something. line is the modem line to be used for this dial. If you select the line, the package tries to dial over that specified line. speed is the speed at which dial the number. If you do not specify the speed, eg. you use the bdial() function, the package will select an unused line that can support that speed. RETURN VALUES:
(bl)dial() return a file descriptor over which you can read/write on the dialed line. If returns < 0, an error was encountered. close_nohangup() is the function that, given the fd returned by one of the dial() functions, close the fd without hanging up the modem line. Be warned: the modem line remains opened so the phone bill is going to grow. Don't forget to hang up the line by some other way or you are going to be fired by someone for the phone bill! hangup() is the function that, given the fd returned by one of the dial() functions, hangs up the communication between your modem and the remote one. RETURN VALUES:
close_nohangup() and hangup() returns the last modem error encountered. Eg.: #include <modems.h> int fd;
FILE *fp; if ((fd = bdial("499782", 19200)) < 0) {
    mdmperror("error on dial");
    exit(-1);
} fp = fdopen(fd, "r+"); fprintf(fp, "\n\nHello remote system.\n");
fprintf(fp, "Now i will hang up. See ya!\n"); hangup(fd);

mdmlock.c
This file contains all the functions related with locks of modem lines. ********************************************************************
*
* #include <modems.h>
*
* extern int mdm_lock(struct modems *mdm);
* extern int mdm_unlock(struct modems *mdm);
* extern int mdm_chklock(struct modems *mdm); in every function mdm is a modems structure of the device that is to be locked/unlocked/checked for lock. mdm_lock() and mdm_chklock() identify and remove stale locks. RETURN VALUES:
mdm_lock() return SUCCESS on a successful lock, otherwise FAILURE
mdm_unlock() return SUCCESS on a successful unlock, otherwise FAILURE
mdm_chklock() return SUCCESS if the line is locked, otherwise FAILURE

mdmerrno.c
This file contains all the functions related with the error status of the libmodem package. ********************************************************************
*
* #include <modems.h>
*
* extern char *_mdm_sys_errlist[];
* extern int mdmerrno;
*
* extern char *mdmstrerror(int);
* void mdmperror(char *);
_mdm_sys_errlist is an array of strings that contain all the modem related error messages. mdmerrno is the actual error status of the package. It can be used to reference the error messages in their array. mdmstrerror() and mdmperror() works just like strerror() and perror()

CONFIGURATION FILE
The /etc/modems is the only configuration file for the libmodem package. Every line of the file describe a modem device, described by a couple of fields. # /etc/modems - example file
#
# This file contains all the modem informations. This is the list
# of the system modems that will be used when callbacking, by the
# library libmodem.a
#
# Format:
#
# line:cp:ce:at:dl:bd:cs:ds:de:im:hu:fc
#
# line: the modem device. If you have a /dev/modem, you will use
# only 'modem' without '/dev/' prefix
# cp:    command prefix (usually AT)
# ce:    command end (suffix)
# at:    attention string (usually +++)
# dl:    delay waiting for OK, in seconds (be warned that a +++ may require a
# long delay
# bd:    max baud rate (every rate below this is allowed)
# cs:    connect string (usually CONNECT)
# ds:    dial string (usually DT for tone or DP for pulse), if null, cannot dial
# de:    dial end
# im:    initialize modem (usually H0V1Q0E1)
# hu:    hangup string (usually H0)
# fc:    flow control (0==Hardware RTS/CTS, 1==XON/XOFF)
#
# Note: ALL the above fields must be present in a modem entry. If set to
# nothing, like '::' it will be NULL, zero, nada, niente! modem:AT::+++:30:14400:CONNECT:DT::ZH0V1Q0E1:H0:0
tty8:AT::+++:30:14400:CONNECT:DT::ZH0V1Q0E1:H0:0

LOCK FILES
Lock files are put in /var/spool/uucp/LCK..line where line is the device name (modem1, modem2, etc), and inside the file, the pid of the process using the fprintf(fp, "%10d", pid)

NOTES
libmodem is written for Linux, but i think you can easily port this package on other platforms (that have POSIX_TERMIOS of course :)) This is an ALPHA version of the code, developed as modem library for another package. The library libmodem is distributed as a package, subjected to the GNU LIBRARY GENERAL PUBLIC LICENSE

BUGS
This is an ALPHA version, so it is quite sure that contain bugs and mistakes. If you find one of them please let me know, e-mail me!

AUTHORS
Riccardo Facchetti
e-mail:    riccardo@cdc8g5.cdc.polimi.it

VERSION
0.99.1 (ALPHA)

COPYRIGHT
(C) 1994, 1995 Riccardo Facchetti under the terms of the
            GNU Library General Public Licence