| | Open Sound System |
| Do you have problems with sound/audio application development? Don't panic! Click here for help! |
oss_midi_info mi;
ai.dev = 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.
The oss_midi_info structure contains the following fields.
| Field | Description |
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). |
| Source | Explanation |
| MIDI_CAP_CLIENT | The device is a client side end of a MIDI loopback pipe |
| MIDI_CAP_EXTERNAL | The device is an external MIDI device/port |
| MIDI_CAP_INOUT | Do not use this in applications |
| MIDI_CAP_INPUT | The MIDI device supports input (recording) |
| MIDI_CAP_INTERNAL | The MIDI device is located "inside" the computer |
| MIDI_CAP_MPU401 | Obsolete MIDI device capability that has no meaning |
| MIDI_CAP_MTCINPUT | The recording device has internal MTC timing generator |
| MIDI_CAP_MTC | The device is special a MTC/SMTPE control device. |
| MIDI_CAP_OUTPUT | The MIDI device supports output (playback) |
| MIDI_CAP_PTOP | The device is wired directly to specific device. |
| MIDI_CAP_SERVER | The device is a server side device of a MIDI loopback pipe. |
| MIDI_CAP_VIRTUAL | The device is not a physical device but a software based one. |
You can use the SNDCTL_SYSINFO ioctl to find out how many devices there are in the system.
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.
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.
| ossinfo.c | The ossinfo program that is included in the OSS package. |