GPIB(3) BSD Library Functions Manual GPIB(3)
NAME
ibclr, ibdev, ibdma, ibeos, ibeot, ibloc, ibonl, ibpad, ibrd, ibsad, ibsic, ibtmo, ibtrg, ibwrt -- GPIB library
LIBRARY
General-Purpose Instrument Bus (GPIB) library (libgpib, -lgpib)
SYNOPSIS
#include <gpib.h>
extern int ibcnt, iberr, ibsta;
int
ibask(int handle, int option, int *retval);
int
ibbna(int handle, char *bdname);
int
ibcac(int handle, int v);
int
ibclr(int handle);
int
ibcmd(int handle, void *buffer, long cnt);
int
ibcmda(int handle, void *buffer, long cnt);
int
ibconfig(int handle, int option, int value);
int
ibdev(int boardID, int pad, int sad, int tmo, int eot, int eos);
int
ibdiag(int handle, void *buffer, long cnt);
int
ibdma(int handle, int v);
int
ibeos(int handle, int eos);
int
ibeot(int handle, int eot);
int
ibevent(int handle, short *event);
int
ibfind(char *bdname);
int
ibgts(int handle, int v);
int
ibist(int handle, int v);
int
iblines(int handle, short *lines);
int
ibllo(int handle);
int
ibln(int handle, int padval, int sadval, short *listenflag);
int
ibloc(int handle);
int
ibonl(int handle, int v);
int
ibpad(int handle, int pad);
int
ibpct(int handle);
int
ibpoke(int handle, int option, int value);
int
ibppc(int handle, int v);
int
ibrd(int handle, void *buffer, long cnt);
int
ibrda(int handle, void *buffer, long cnt);
int
ibrdf(int handle, char *flname);
int
ibrdkey(int handle, void *buffer, int cnt);
int
ibrpp(int handle, char *ppr);
int
ibrsc(int handle, int v);
int
ibrsp(int handle, char *spr);
int
ibrsv(int handle, int v);
int
ibsad(int handle, int sad);
int
ibsgnl(int handle, int v);
int
ibsic(int handle);
int
ibsre(int handle, int v);
int
ibsrq((*func) void));
int
ibstop(int handle);
int
ibtmo(int handle, int tmo);
int
ibtrap(int mask, int mode);
int
ibtrg(int handle);
int
ibwait(int handle, int mask);
int
ibwrt(int handle, const void *buffer, long cnt);
int
ibwrta(int handle, const void *buffer, long cnt);
int
ibwrtf(int handle, const char *flname);
int
ibwrtkey(int handle, const void *buffer, int cnt);
int
ibxtrc(int handle, void *buffer, long cnt);
DESCRIPTION
The ibclr library provides access to the gpib(4) kernel devices.
Variable Description
The variable ibcnt contains the number of bytes transferred in the most recent call to ibcmd(), ibrd(), or ibwrt().
The name ibcntl is an alias for ibcnt, provided for backwards compatibility.
The variable iberr provides an error code for the most recent library call. The possible error codes are:
EDVR System error
ECIC Not Active Controller
ENOL Nobody listening
EADR Controller not addressed
EARG Invalid argument
ESAC Not System Controller
EABO I/O Aborted/Time out
ENEB No such controller
EOIP Async I/O in progress
ECAP No such capability
EFSO File system error
EBUS Command byte xfer error
ESTB Serial poll status byte lost
ESRQ SRQ line stuck
ETAB Table problem
The variable ibsta contains the controller status. This is an ORed status value, with the following individual bit names:
ERR Error
TIMO Timeout
END EOI/EOS
SRQI SRQ
RQS Device requests service
SPOLL Serial Poll
EVENT Event occurred
CMPL I/O complete
LOK Lockout
REM Remote
CIC CIC
ATN ATN
TACS Talker
LACS Listener
DTAS Device trigger status
DCAS Device clear state
Function Description
The function ibdev() is used to open the GPIB device, and establish the parameters to communicate with a particular bus device. The device is
selected by its primary address pad, a numerical value between 0 and 30, possibly additionally by its secondary address sad, a numerical
value between 96 and 126, or 0 to not use secondary addressing. The tmo value specifies the timeout to use when communicating with the
device. This can be any of the constants TNONE, T10us, T30us, T100us, T300us, T1ms, T3ms, T10ms, T30ms, T100ms, T300ms, T1s, T3s, T10s,
T30s, T100s, T300s, or T1000s. The boolean parameter eot specifies whether the bus signal EOI (end-or-identify) should be asserted when
sending the last byte of a message to the device. Finally, the eos parameter determines whether any special character should be used to
identify the end of a device message when transferring messages on the bus. The lower 8 bits of eos are interpreted as an end-of-string
character, EOS. This character can be ORed with the following values:
REOS When receiving a message byte on the bus that matches the EOS character, treat it as if the EOI signal were asserted, and stop
receiving.
XEOS When transmitting a message byte on the bus that matches the EOS character, assert the EOI bus signal by the same time, and
stop sending.
BIN If set, include all 8 bits of the EOS character in the comparison; if unset, compare only 7 bit ASCII values.
Passing 0 as eos will turn off any special character treatment, allowing for a fully 8-bit transparent communications channel to the device.
The function ibfind() is meant to find the board index of a board identified by the name bdname. This function is currently not implemented.
All remaining functions take the handle returned by calling ibdev() as their first argument handle.
The function ibask() is used to query configuration values that have been set with ibconfig(). This function is currently not implemented.
The function ibbna() is meant to change the access board for the given device to a new one, named bdname. This function is currently not
implemented.
The function ibcac() is used to become the active controller on the bus, by asserting the ATN signal line. This function is currently not
implemented.
The function ibclr() is used to transmit a Selected Device Clear command to the device.
The function ibcmd() is used to directly write cnt GPIB command bytes from a buffer starting at buffer to the device. This function is
currently not implemented.
The function ibcmda() does the same as ibcmd() except it operates asynchronously, so it returns to the caller immediately. This function is
currently not implemented.
The function ibconfig() is used to set certain configuration parameters. This function is currently not implemented.
The function ibdiag() is obsolete, and not implemented.
The function ibdma() is used to enable or disable DMA transfers. Parameter v is a boolean parameter indicating DMA transfers are to be used.
Depending on the hardware and operating system configuration, DMA transfers might not be available for a particular access board.
The function ibeos() configures the end-of-string character. See ibdev() for an explanation.
The function ibeot() configures the assertion of the EOI signal line when transmitting the last byte of a message; see ibdev() for an expla-
nation.
The function ibevent() is used to obtain an event from the board's event queue. This function is currently not implemented.
The function ibgts() makes the current controller the standby controller, by deasserting the ATN signal line. This function is currently not
implemented.
The function ibist() sets the individual status bits of the controller to the value v. This function is currently not implemented.
The function iblines() returns the status of the control and handshake bus lines into the area pointed to by lines. This function is
currently not implemented.
The function ibllo() is obsolete, and not implemented.
The function ibln() checks for a listener at the primary address padval and the optional secondary address sadval. If a listener was found,
the value pointed to by listenflag will be set to a non-zero value. This function is currently not implemented.
The function ibloc() turns the device into local mode.
The function ibonl() is used to close or reinitialize a device handle. If parameter v is passed as zero, the handle will be closed, and can-
not be used again. If it is passed as a non-zero value, all parameters of the handle will be returned to their defaults; this functionality
is currently unsupported.
The function ibpad() is used to change the primary address of the device being communicated with to pad. See ibdev() for an explanation.
The function ibpct() is used to make the device associated with the handle the controller-in-charge. This function is currently not
implemented.
The function ibpoke() is obsolete, and not implemented.
The function ibppc() is used to configure the parallel poll response to v. This function is currently not implemented.
The function ibrd() is used to receive cnt bytes from the device, and store it to the address passed as buffer.
The function ibrda() behaves similar to ibrd() except it operates asynchronously, and returns immediately to the caller. This function is
currently not implemented.
The function ibrdf() read data from the device, and appends it to the file with the name flname. This function is currently not implemented.
The function ibrdkey() is obsolete, and not implemented.
The function ibrpp() performs a parallel poll, and stores the result at the location pointed to by ppr. This function is currently not
implemented.
The function ibrsc() makes the board specified by the handle the system controller if the argument v is non-zero. This function is currently
not implemented.
The function ibrsp() conducts a serial poll, and stores the result in the byte pointed to by spr. This function is currently not
implemented.
The function ibrsv() sets the serial poll response of the board to v, possibly requesting service from the controller if the SRQ bit (0x40)
is set. This function is currently not implemented.
The function ibsad() changes the secondary address of the device being communicated with to sad. See ibdev() for an explanation.
The function ibsgnl() is obsolete, and not implemented.
The function ibsic() asserts the Interface Clear (IFC) signal line on the bus for at least 100 microseconds. This will make all devices
attached to the bus to unlisten and untalk. This function should only be executed on the system controller.
The function ibsre() asserts the Remote Enable (REN) signal line on the bus if argument v is non-zero, or deasserts it otherwise. This
function is currently not implemented.
The function ibsrq() is obsolete, and not implemented.
The function ibstop() stops or aborts any asynchronous I/O operation. This function is currently not implemented.
The function ibtmo() reconfigures the communication timeout. See ibdev() for an explanation.
The function ibtrap() is obsolete, and not implemented.
The function ibtrg() sends a Group Execute Trigger (GET) command to the device.
The function ibwait() waits for a status condition as specified by mask. If mask is given as zero, it returns immediately. This function is
currently not implemented.
The function ibwrt() is used to send cnt bytes to the device, starting at the address pointed to by buffer.
The function ibwrta() performs the same operation as ibwrt() in an asynchronous way, returning immediately to the caller. This function is
currently not implemented.
The function ibwrtf() opens the file named by flname, and sends its contents to the device. This function is currently not implemented.
The function ibwrtkey() is obsolete, and not implemented.
The function ibxtrc() is obsolete, and not implemented.
RETURN VALUES
The function ibdev() returns a handle to be used for the remaining functions. Upon failure, -1 is returned.
All other functions return the value of the variable ibsta.
DIAGNOSTICS
None.
COMPATIBILITY
The ibclr library tries to be compatible with the Linux GPIB library, which in turn appears to be compatible with the GPIB library shipped by
National Instruments.
ERRORS
Errors in the functions above might set errno to one of these values:
[ENOENT] No such file or directory.
[EIO] Input/output error.
[ENXIO] Device not configured.
[E2BIG] Argument list too long.
[ENOMEM] Cannot allocate memory.
[EACCES] Permission denied.
[EFAULT] Bad address.
[EBUSY] Device busy.
[EINVAL] Invalid argument.
[ENFILE] Too many open files in system.
[EMFILE] Too many open files.
[EOPNOTSUPP] Operation not supported.
SEE ALSO
gpib(4)
HISTORY
The ibclr library was written by Poul-Henning Kamp and first appeared in FreeBSD 5.4.
AUTHORS
This manual page was written by Jorg Wunsch.
BUGS
Currently, the library can only handle a single gpib(4) device with instance number 0.
Many functions are currently not implemented, see above for details.
BSD
February 1, 2010 BSD