Open Sound System
OSS 4.x Programmer's Guide

Do you have problems with sound/audio application development? Don't panic! Click here for help!


Returns information about a MIDI device


oss_midi_info mi; = The midi device number.
ioctl(fd, SNDCTL_MIDIINFO, &mi);

The above code fragment lacks all error checks for clarity. Real world applications must always check for the errors and handle them as described below. Also most OSS ioctl calls will return information in the argument variable and it's usually necessary to check it too.


This ioctl call is supported by all OSS devices, including audio, mixer and MIDI devices.

Typically this ioctl call is used by MIDI applications to select the MIDI input and/or output device. Applications using this call should first use SNDCTL_SYSINFO to find out the number of MIDI devices in the system. Then SNDCTL_MIDIINFO can be called for each device number between 0 and sysinfo.nummidis-1.

OSS version 4.0 doesn't have any MIDI support so using this ioctl is rather pointless at this moment. MIDI support will be introduced in OSS 4.1.

Description of the oss_midi_info fields

The oss_midi_info structure contains the following fields.

dev The MIDI device number. Must be set before calling ioctl(). Setting dev=-1 will return information about the MIDI device pointed by the fd parameter.
name Name of the device (up to 63 characters).
busy Will be set to 0 if the device is currently not in use. Other possible return values are OSS_OPEN_READ, OSS_OPEN_WRITE and OSS_OPEN_READWRITE. Used by the ossinfo program. Other programs hould not use this field.
pid PID of the process currently using the device. Value of -1 means that the PID is not known or the device is not open by any applications. Value of 0 means that the device is being used by some internal subsystem of OSS (or the OSS implementation doesn't support this field).
cmd Program name of the process currently using the device. Empty if the program is not known.
caps Capabilities of the device (bitmask). Possible capabilities will be defined below.
magic This field is reserved for use by private setup utilities for given MIDI device (for example firmware downloader). By using this field the utility may find the right MIDI device.
card_number Card number of the sound card that owns this MIDI device. Note that OSS API doesn't have any concept of "card" and this field is practically meaningless. Applications should avoid using this field.
port_number MIDI port number (0 to N-1) within the sound card. Use of this field should be avoided in applications.
handle A short identifier (string) that uniquely identifies the physical hardware device/port. The device number (dev as well as the card_number fields may change if a new audio device is installed in the system. This field is designed to have the same value even after that (provided that the device is not moved to some other PCI slot or USB port. This is just an arbitrary character string that the applications should not try to interpret. The only permitted use is comparing against some previously stored handle in application's configuration files.
devnode The device special file name associated with this MIDI device. Note that this field has been added to the oss_audioinfo structure recently and it will be empty with earlier OSS versions. In that case applications should use the real_device field as the /dev/midi# number for this device.
legacy_device *OBSOLETE* Use the devnode field instead. This field is the /dev/midi## "legacy" device number. The device number for given device may change without notice. Applications that store the device numbers in their configuration files are likely to cause serious privacy problems when device numbers change. New applications written for OSS 4.0 or later should use the devnode field to find out which device file to open. Value of -1 means that this device doesn't have any legacy /dev/midi## device (this alternative is used with certain special purpose devices).
enabled Usually 1. However it will be set to 0 if the device is (temporarily) unavailable. This may happen for example if an USB device is "hot" unplugged from the system.
flags Reserved for internal use by OSS. Usage of this field may change between OSS builds without any notice.
song_name A string of 0 to 63 characters that contains the song name the device is currently playing. May be set by the application that uses the device (see SNDCTL_SETSONG).
label A string of 0 to 31 characters that contains a label assigned to the device. May be set by the application that uses the device (see SNDCTL_SETLABEL).
latency Nominal latency of the device in microseconds. Value of -1 means that the latency is not known. This field is reserved for OSS utilities like ossinfo. Other applications should not use this field for anything. OSS will use the latency reported by the device and automatically send timed events to the device 'latency' microseconds earlier (within the available timer precision). So applications must NOT use this field in their internal timing computations (that would result in event's played in advance).

MIDI device capabilities

MIDI_CAP_CLIENTThe device is a client side end of a MIDI loopback pipe
MIDI_CAP_EXTERNALThe device is an external MIDI device/port
MIDI_CAP_INOUTDo not use this in applications
MIDI_CAP_INPUTThe MIDI device supports input (recording)
MIDI_CAP_INTERNALThe MIDI device is located "inside" the computer
MIDI_CAP_MPU401Obsolete MIDI device capability that has no meaning
MIDI_CAP_MTCINPUTThe recording device has internal MTC timing generator
MIDI_CAP_MTCThe device is special a MTC/SMTPE control device.
MIDI_CAP_OUTPUTThe MIDI device supports output (playback)
MIDI_CAP_PTOPThe device is wired directly to specific device.
MIDI_CAP_SERVERThe device is a server side device of a MIDI loopback pipe.
MIDI_CAP_VIRTUALThe device is not a physical device but a software based one.

Related ioctl calls

You can use the SNDCTL_SYSINFO ioctl to find out how many devices there are in the system.

Compatibility issues

This ioctl call is new in OSS 4.0 and not supported by the freeware implementations based on older OSS versions. If this call returns errno=EINVAL then MIDI device information is not available from this OSS implementation. The best backup plan is to let the user to enter the /dev/midiN device name manually.

OSS ioctl return values

The return value from the OSS ioctl calls will be -1 if a fatal error occurred. Other values mean that the ioctl call was more or less successful. However in most cases the application must check the value returned in the argument to see what was the accepted value.

Please see the Possible error codes (errno) returned by OSS calls section for more info about the error codes returned by OSS.

Sample programs

ossinfo.cThe ossinfo program that is included in the OSS package.

Copyright (C) 4Front Technologies, 2007. All rights reserved.
Back to index OSS web site