MANUAL:

-- 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
#
# 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:dp: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
# dp:   dial prefix (e.g. strings to get the line: '0,')
# 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:

/var/spool/uucp/LCK..<line>

where the <line> is the device name (modem1, modem2, etc), and inside the file,
the pid of the process using the line (fprintf(fp, "%10d", pid)).

-- header files:

<dial/modems.h>
<dial/mdmerrno.h> (included by 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 modem */
	int bd;				/* max baud rate */
	char cs[MAXMDMCMD];		/* connect string */
	char ds[MAXMDMCMD];		/* dial string */
	char dp[MAXMDMCMD];		/* dial prefix */
	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: 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: getnextmdm() return a poniter 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) {
	...
}
...
********************************************************************

/*
 * 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);
*
* extern struct modems *mdmopendevice; /* the actually opened device */
*
* (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: (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 a function that close the fd, but don't hangup the modem
* line.
*
* 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: 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: 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()
*
********************************************************************
