libscsi

A Library for Direct SCSI Device Access

For version {No value for ‘VERSION’}, {No value for ‘UPDATED’}

Copyright © 1996 Dieter Baron and Armin Obersteiner

This is a draft edition of the libscsi documentation,
and is consistent with libscsi {No value for ‘VERSION’}.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.

1 Introduction

Some applications (such as cd players and cd writers) need direct access to SCSI devices. Although most operating system provide such services, each does so in a different way; writing portable software is painfull.

One goal of libscsi is to encapsulate these system dependencies and to provide a uniform interface to the application. See section Low Level Functions.

The other is to provide convenience functions for SCSI commands, to avoid programming errors and to render programs more readable. These are grouped according to the sections of X3.131 (the ANSI standard for SCSI II) or devices for vendor specific commands.

2 Low Level Functions

Function: SCSI * sc_open (char *device)

Function: int sc_close (SCSI *sdev)

sc_close closes device sdev, deallocating all resources associated with it. sdev must not be passed to any libscsi function afterwards.

Function: int sc_send (SCSI *sdev, int direction, int cmdlen, char *cmd, int datalen, char *data)

The sc_send function sends a command to device sdev.

cmd is the command descriptor block (CDB) of the command, cmdlen its length (in bytes).

Set direction to SC_READ if data will be transferred from the device to the host in the data in phase; to SC_WRITE if data will be transferred to the device during data out phase; or to 0 if no data (besides the CDB) will be transferred.

If this is a write command (SC_WRITE), data points to datalen bytes to be transferred. If it is a read command (SC_READ), up to datalen bytes will be placed in data.

On success, sc_send return 0 for write and transferless commands and the number of bytes read on read commands. On error, -1 is returend and the error indicator and sense data in sdev are set.

Function: int sc_set_timeout (SCSI *sdev, u_long timeout)

On systems that timeout commands, sc_set_timeout is used to specify a timeout of timeout milliseconds for command completion on device sdev.

If the timeout cannot be set as specified, -1 is returned. However, if the system does not timeout commands, this function is a noop, and 0 is returned.

If the underlying system supports only one global timeout value for all devices, it is expected of the interface functions to set it appropriatly for each device before sending a command.

3 Extending libscsi

You have to create the files 'lib/xx_????.c' and 'scsi/xx.h' (or just
add prototypes to it).

  xx   - command type OR device type OR product
  ???? - command name

If you've included more commands or support for other devices please
contact us for inclusion in our distribution.

4 Porting libscsi to other platforms

To port libscsi to a new platform, you have to provide definitions for the SCSI structure and the low level functions sc_open, sc_close, sc_send, and sc_set_timeout. They should behave as documented in See section Low Level Functions. Look at the provided interfaces (scsi/os_{netbsd,amiga}.h and lib/os_{netbsd,amiga}.c) for examples.

Remove the symbolic links scsi/os.h and lib/os.c, and place your header and soruce files there.

If you want to make your interface part of the distribution, pick a name and place it in the files scsi/os_name.h and lib/os_name.c. Also, edit configure.in to recognize systems supporting your interface.

Also, send us your new interface, so we can include it in future releases.

5 Notes on the Interfaces

This section contains interface specific notes, such as the syntax and semantics of device names or constraints.

5.1 AmigaDOS

• - compiling and developing
  You simply need the ’gcc’ or ’ADE’ environment installed ...
• - device names
  SCSI devices are used in following notation

  device:unit
  

  For example, gvpscsi.device:2, or simplified, gvpscsi:2. Also, gvpscsi is equivalent to gvpscsi.device:0 and gvpscsi:0.

• - platform information
  Any Amiga with Kickstart 2.04+ and SCSI controller will do. (With a few changes Kickstart 1.3 would work too.)

  Developed and tested with: A2000 (total 7MB), A2630 (2MB), GVP Series II, some SCSI devices: hd, cd, zip.

5.2 NetBSD

• - device names
  Under NetBSD, SCSI device names are file names for character special devices, usually partition d. (So, for sd0, the zeroth SCSI hard disk, the name would be /dev/rsd0d.) As a shorthand, one can specify the device (e.g. sd0), rather than the file name.
• - opening a device
  Since a character special device file is opened (from which reads are possible), NetBSD ensures that a medium is present and the device is ready. For a direct SCSI interface, however, this may prove disadvantageous.

Index

Index of Functions

Index of Variables and Types

Table of Contents

About This Document

This document was generated on March 28, 2025 using texi2html 5.0.

The buttons in the navigation panels have the following meaning:

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

• 1. Section One
  • 1.1 Subsection One-One
    • ...
  • 1.2 Subsection One-Two
    • 1.2.1 Subsubsection One-Two-One
    • 1.2.2 Subsubsection One-Two-Two
    • 1.2.3 Subsubsection One-Two-Three     <== Current Position
    • 1.2.4 Subsubsection One-Two-Four
  • 1.3 Subsection One-Three
    • ...
  • 1.4 Subsection One-Four

This document was generated on March 28, 2025 using texi2html 5.0.