CINXE.COM

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html lang="en-US"> <head>  <meta http-equiv="Content-type" content="text/html; charset=utf-8"> <title>Synopsis - man pages section 7: Device and Network Interfaces</title> <meta http-equiv="content-language" content="en-US"> <meta name="robots" content="index,follow"> <meta name="language" content="en"> <meta name="collection" content="reference"> <meta name="keywords" content=""> <meta name="description" content="This section describes the various device and network interfaces available on the system. It includes descriptions of character and block devices, STREAMS modules, network protocols, file systems and ioctl requests for driver subsystems and classes.This section is for software engineers who write, maintain or modify device drivers."> <meta name="date" content="2013-01-01"> <link rel="stylesheet" type="text/css" title="screen" href="css/default.css"> <link rel="stylesheet" type="text/css" title="screen" href="css/pagelayout.css"> <link rel="alternate stylesheet" type="text/css" title="print" href="css/print.css"> <link rel="stylesheet" type="text/css" title="screen" href="css/advanced.css"> <link rel="stylesheet" type="text/css" title="screen" href="css/search.css"> <script type="text/javascript" src="css/util.js"></script> <script type="text/javascript"> function SubmitSearch() { var form = document.getElementById("SearchForm"); var searchterm = document.getElementById("searchterm"); var q = document.getElementById("q"); var scope; var library; var path; for (var i=0; i < form.scope.length; i++) { if (form.scope[i].checked) { scope = form.scope[i].value; } } if (searchterm.value.length == 0) { alert("search field is empty"); return false; } path = "docs/cd/E26505_01/html/816-5177"; if (scope == "doc") { q.value = searchterm.value + " url:/" + path; } else { library = path.match(/docs.cd.[A-Z][0-9,_]*/); // This is a regular expressions -- . is used in place of / for path separators if (library == null) { library = path; } q.value = searchterm.value + " url:/" + library; } form.action = "http://search.oracle.com/search/search"; form.method = "get"; form.target = "_top"; form.submit(); } </script> <noscript> JavaScript is required to for searching. </noscript> <script>window.ohcglobal || document.write('<script src="/en/dcommon/js/global.js">\x3C/script>')</script></head> <body> <div class="MastheadPane"> <table class="MastheadTable" width="100%"> <tr class="skipnavigation"> <td> <a href="#content">Skip Navigation Links</a> </td> </tr> <tr class="closeprintview"> <td align="right"> <a href="#" onclick="setActiveStyleSheet('screen')">Exit Print View</a> </td> </tr> <tr class="titlebar"> <td class="smallLogo"><a href="http://www.oracle.com"><img alt="Link to oracle.com" src="graphics/smallOracleLogo.gif"></a> </td> <td class="contentpage-doctitle"><a href="toc.html">man pages section 7: Device and Network Interfaces </a>    Oracle Solaris 10 1/13 Information Library </td> </tr> </table> </div> <div class="ButtonPane"> <div class="ButtonArea1"> <div class="Button"> <a href="http://www.oracle.com/technology/documentation/index.html" > <img border="0" src="graphics/btn_otn.png" alt="Oracle Technology Network" title="Oracle Technology Network"> </a> </div> <div class="Button"> <a href="../../index.html " > <img border="0" src="graphics/btn_library.png" alt="Library" title="Library"> </a> </div> </div> <div class="ButtonArea2"> <div class="Button"> <a href="../../pdf/816-5177.pdf" target="table4" onclick="openPopup('','table4',550,550,'yes',0,0,0,0,0,0); return true;"> <img border="0" src="graphics/btn_pdf.png" alt="PDF" title="PDF"> </a>  </div> <div class="Button"> <a href="#" onclick="setActiveStyleSheet('print')"> <img border="0" src="graphics/btn_print-view.png" alt="Print View" title="Print View"> </a> </div>  <div class="Button"> <a href="http://www.oracle.com/goto/docfeedback" target="new"> <img border="0" src="graphics/btn_feedback.png" alt="Feedback" title="Feedback"> </a> </div> </div> <div style="WIDTH: 173px; FLOAT: right; clear: right; margin-right: 30px"> <div class="search_position" id="img5"> <form id="SearchForm" name="SearchForm" onsubmit="SubmitSearch()"> <input name="q" id="q" value="" type="hidden"> <div id="serch_txtbox"> <div class="search_text"> <a onclick="mvqMOv('panelDiv_search','img5');" href="#"><img alt="search filter icon" src="graphics/search-filter-btn.png" /></a> </div> <div class="textbg"> <input title="Search" id="searchterm" name="searchterm" class="textcnt" value="Search" onClick="javascript:if(!isUserInput) {document.SearchForm.searchterm.value='';}" onKeyDown="javascript:isUserInput=true;" onMouseDown="javascript:if(!isUserInput) {document.SearchForm.searchterm.value='';}" /> <input type="hidden" name="keyword" value="" id="keyword"/> </div> <div class="search_button"> <a onClick="SubmitSearch()"><img alt="search icon" src="graphics/search-icon.gif" /></a> </div> </div> <div id="panelDiv_search" onMouseOver="mvqMOv('panelDiv_search','img5');" onMouseOut="mvqMOu('panelDiv_search')";> <div class="TopleftCurv"></div> <div class="centerTop"></div> <div class="ToprightCurv"></div> <div class="contentBg"> Search Scope: <div style="padding-bottom:5px; *padding-bottom:1px;"></div> <ul> <li><input id="radio_doc" value="doc" type="radio" name="scope" onclick="mvqMOu('panelDiv_search')"/><label for="radio_doc">  This Document</label></li> <li><input id="radio_lib" value="library" type="radio" name="scope" onclick="mvqMOu('panelDiv_search')" /><label for="radio_lib">  Entire Library</label></li> </ul> </div> <div class="BottomleftCurv"></div> <div class="centerBottom"></div> <div class="BottomrightCurv"></div> </div> <input type="hidden" name="group" value="Documentation" id="group"/> </form> </div> </div> </div> <div class="TOCPane"> <a href="docinfo.html#scrolltoc">Document Information</a> <a href="gentextid-47.html#scrolltoc">Preface</a> <a href="gentextid-205.html#scrolltoc">Introduction</a> <a href="gentextid-362.html#scrolltoc">Device and Network Interfaces</a> <a href="x-6to4-7m.html#scrolltoc"><tt>6to4</tt>(7M)</a> <a href="x-6to4tun-7m.html#scrolltoc"><tt>6to4tun</tt>(7M)</a> <a href="aac-7d.html#scrolltoc"><tt>aac</tt>(7D)</a> <a href="adp-7d.html#scrolltoc"><tt>adp</tt>(7D)</a> <a href="adpu320-7d.html#scrolltoc"><tt>adpu320</tt>(7D)</a> <a href="afb-7d.html#scrolltoc"><tt>afb</tt>(7d)</a> <a href="agpgart-io-7i.html#scrolltoc"><tt>agpgart_io</tt>(7I)</a> <a href="ah-7p.html#scrolltoc"><tt>AH</tt>(7P)</a> <a href="ahci-7d.html#scrolltoc"><tt>ahci</tt>(7D)</a> <a href="allkmem-7d.html#scrolltoc"><tt>allkmem</tt>(7D)</a> <a href="amd8111s-7d.html#scrolltoc"><tt>amd8111s</tt>(7D)</a> <a href="amr-7d.html#scrolltoc"><tt>amr</tt>(7D)</a> <a href="z-arp-7p.html#scrolltoc"><tt>ARP</tt>(7P)</a> <a href="arp-7p.html#scrolltoc"><tt>arp</tt>(7P)</a> <a href="ast-7d.html#scrolltoc"><tt>ast</tt>(7D)</a> <a href="asy-7d.html#scrolltoc"><tt>asy</tt>(7D)</a> <a href="ata-7d.html#scrolltoc"><tt>ata</tt>(7D)</a> <a href="atun-7m.html#scrolltoc"><tt>atun</tt>(7M)</a> <a href="audio1575-7d.html#scrolltoc"><tt>audio1575</tt>(7D)</a> <div id="scrolltoc" class="onpage"> <a href="#scrolltoc"><tt>audio</tt>(7I)</a> </div> <a href="audio810-7d.html#scrolltoc"><tt>audio810</tt>(7D)</a> <a href="audiocs-7d.html#scrolltoc"><tt>audiocs</tt>(7D)</a> <a href="audioens-7d.html#scrolltoc"><tt>audioens</tt>(7D)</a> <a href="audiohd-7d.html#scrolltoc"><tt>audiohd</tt>(7D)</a> <a href="audioixp-7d.html#scrolltoc"><tt>audioixp</tt>(7D)</a> <a href="audio-support-7i.html#scrolltoc"><tt>audio_support</tt>(7I)</a> <a href="audiots-7d.html#scrolltoc"><tt>audiots</tt>(7D)</a> <a href="audiovia823x-7d.html#scrolltoc"><tt>audiovia823x</tt>(7D)</a> <a href="av1394-7d.html#scrolltoc"><tt>av1394</tt>(7D)</a> <a href="bbc-beep-7d.html#scrolltoc"><tt>bbc_beep</tt>(7D)</a> <a href="bcm-sata-7d.html#scrolltoc"><tt>bcm_sata</tt>(7D)</a> <a href="bd-7m.html#scrolltoc"><tt>bd</tt>(7M)</a> <a href="bge-7d.html#scrolltoc"><tt>bge</tt>(7D)</a> <a href="bmc-7d.html#scrolltoc"><tt>bmc</tt>(7D)</a> <a href="bnx-7d.html#scrolltoc"><tt>bnx</tt>(7D)</a> <a href="bnxe-7d.html#scrolltoc"><tt>bnxe</tt>(7D)</a> <a href="bpp-7d.html#scrolltoc"><tt>bpp</tt>(7D)</a> <a href="bscbus-7d.html#scrolltoc"><tt>bscbus</tt>(7D)</a> <a href="bscv-7d.html#scrolltoc"><tt>bscv</tt>(7D)</a> <a href="bufmod-7m.html#scrolltoc"><tt>bufmod</tt>(7M)</a> <a href="cadp160-7d.html#scrolltoc"><tt>cadp160</tt>(7D)</a> <a href="cadp-7d.html#scrolltoc"><tt>cadp</tt>(7D)</a> <a href="cdio-7i.html#scrolltoc"><tt>cdio</tt>(7I)</a> <a href="ce-7d.html#scrolltoc"><tt>ce</tt>(7D)</a> <a href="cgsix-7d.html#scrolltoc"><tt>cgsix</tt>(7D)</a> <a href="chxge-7d.html#scrolltoc"><tt>chxge</tt>(7D)</a> <a href="cmdk-7d.html#scrolltoc"><tt>cmdk</tt>(7D)</a> <a href="connld-7m.html#scrolltoc"><tt>connld</tt>(7M)</a> <a href="console-7d.html#scrolltoc"><tt>console</tt>(7D)</a> <a href="cpqary3-7d.html#scrolltoc"><tt>cpqary3</tt>(7D)</a> <a href="cpr-7.html#scrolltoc"><tt>cpr</tt>(7)</a> <a href="cpuid-7d.html#scrolltoc"><tt>cpuid</tt>(7D)</a> <a href="ctfs-7fs.html#scrolltoc"><tt>ctfs</tt>(7FS)</a> <a href="ctsmc-7d.html#scrolltoc"><tt>ctsmc</tt>(7D)</a> <a href="cvc-7d.html#scrolltoc"><tt>cvc</tt>(7D)</a> <a href="cvcredir-7d.html#scrolltoc"><tt>cvcredir</tt>(7D)</a> <a href="dad-7d.html#scrolltoc"><tt>dad</tt>(7D)</a> <a href="daplt-7d.html#scrolltoc"><tt>daplt</tt>(7D)</a> <a href="dbri-7d.html#scrolltoc"><tt>dbri</tt>(7D)</a> <a href="dca-7d.html#scrolltoc"><tt>dca</tt>(7D)</a> <a href="dcam1394-7d.html#scrolltoc"><tt>dcam1394</tt>(7D)</a> <a href="dcfs-7fs.html#scrolltoc"><tt>dcfs</tt>(7FS)</a> <a href="devfs-7fs.html#scrolltoc"><tt>devfs</tt>(7FS)</a> <a href="devinfo-7d.html#scrolltoc"><tt>devinfo</tt>(7D)</a> <a href="dkio-7i.html#scrolltoc"><tt>dkio</tt>(7I)</a> <a href="dlcosmk-7ipp.html#scrolltoc"><tt>dlcosmk</tt>(7ipp)</a> <a href="dlpi-7p.html#scrolltoc"><tt>dlpi</tt>(7P)</a> <a href="dm2s-7d.html#scrolltoc"><tt>dm2s</tt>(7D)</a> <a href="dmfe-7d.html#scrolltoc"><tt>dmfe</tt>(7D)</a> <a href="dnet-7d.html#scrolltoc"><tt>dnet</tt>(7D)</a> <a href="dr-7d.html#scrolltoc"><tt>dr</tt>(7d)</a> <a href="drmach-7d.html#scrolltoc"><tt>drmach</tt>(7d)</a> <a href="dscpmk-7ipp.html#scrolltoc"><tt>dscpmk</tt>(7ipp)</a> <a href="dtrace-7d.html#scrolltoc"><tt>dtrace</tt>(7D)</a> <a href="e1000-7d.html#scrolltoc"><tt>e1000</tt>(7D)</a> <a href="e1000g-7d.html#scrolltoc"><tt>e1000g</tt>(7D)</a> <a href="ecpp-7d.html#scrolltoc"><tt>ecpp</tt>(7D)</a> <a href="efb-7d.html#scrolltoc"><tt>efb</tt>(7D)</a> <a href="ehci-7d.html#scrolltoc"><tt>ehci</tt>(7D)</a> <a href="elxl-7d.html#scrolltoc"><tt>elxl</tt>(7D)</a> <a href="emlxs-7d.html#scrolltoc"><tt>emlxs</tt>(7D)</a> <a href="eri-7d.html#scrolltoc"><tt>eri</tt>(7D)</a> <a href="esp-7d.html#scrolltoc"><tt>esp</tt>(7D)</a> <a href="esp-7p.html#scrolltoc"><tt>ESP</tt>(7P)</a> <a href="fas-7d.html#scrolltoc"><tt>fas</tt>(7D)</a> <a href="fasttrap-7d.html#scrolltoc"><tt>fasttrap</tt>(7D)</a> <a href="fbio-7i.html#scrolltoc"><tt>fbio</tt>(7I)</a> <a href="fbt-7d.html#scrolltoc"><tt>fbt</tt>(7D)</a> <a href="fcip-7d.html#scrolltoc"><tt>fcip</tt>(7D)</a> <a href="fcp-7d.html#scrolltoc"><tt>fcp</tt>(7D)</a> <a href="fctl-7d.html#scrolltoc"><tt>fctl</tt>(7D)</a> <a href="fd-7d.html#scrolltoc"><tt>fd</tt>(7D)</a> <a href="fdc-7d.html#scrolltoc"><tt>fdc</tt>(7D)</a> <a href="fdio-7i.html#scrolltoc"><tt>fdio</tt>(7I)</a> <a href="ffb-7d.html#scrolltoc"><tt>ffb</tt>(7D)</a> <a href="firewire-7d.html#scrolltoc"><tt>firewire</tt>(7D)</a> <a href="flowacct-7ipp.html#scrolltoc"><tt>flowacct</tt>(7ipp)</a> <a href="fp-7d.html#scrolltoc"><tt>fp</tt>(7d)</a> <a href="fss-7.html#scrolltoc"><tt>FSS</tt>(7)</a> <a href="ge-7d.html#scrolltoc"><tt>ge</tt>(7D)</a> <a href="gld-7d.html#scrolltoc"><tt>gld</tt>(7D)</a> <a href="glm-7d.html#scrolltoc"><tt>glm</tt>(7D)</a> <a href="gpio-87317-7d.html#scrolltoc"><tt>gpio_87317</tt>(7D)</a> <a href="grbeep-7d.html#scrolltoc"><tt>grbeep</tt>(7d)</a> <a href="hci1394-7d.html#scrolltoc"><tt>hci1394</tt>(7D)</a> <a href="hdio-7i.html#scrolltoc"><tt>hdio</tt>(7I)</a> <a href="hermon-7d.html#scrolltoc"><tt>hermon</tt>(7D)</a> <a href="hid-7d.html#scrolltoc"><tt>hid</tt>(7D)</a> <a href="hme-7d.html#scrolltoc"><tt>hme</tt>(7D)</a> <a href="hpfc-7d.html#scrolltoc"><tt>hpfc</tt>(7D)</a> <a href="hsfs-7fs.html#scrolltoc"><tt>hsfs</tt>(7FS)</a> <a href="hubd-7d.html#scrolltoc"><tt>hubd</tt>(7D)</a> <a href="hxge-7d.html#scrolltoc"><tt>hxge</tt>(7D)</a> <a href="i2bsc-7d.html#scrolltoc"><tt>i2bsc</tt>(7D)</a> <a href="i2o-bs-7d.html#scrolltoc"><tt>i2o_bs</tt>(7D)</a> <a href="i2o-scsi-7d.html#scrolltoc"><tt>i2o_scsi</tt>(7D)</a> <a href="ib-7d.html#scrolltoc"><tt>ib</tt>(7D)</a> <a href="ibcm-7d.html#scrolltoc"><tt>ibcm</tt>(7D)</a> <a href="ibd-7d.html#scrolltoc"><tt>ibd</tt>(7D)</a> <a href="ibdm-7d.html#scrolltoc"><tt>ibdm</tt>(7D)</a> <a href="ibmf-7.html#scrolltoc"><tt>ibmf</tt>(7)</a> <a href="ibtl-7d.html#scrolltoc"><tt>ibtl</tt>(7D)</a> <a href="icmp6-7p.html#scrolltoc"><tt>icmp6</tt>(7P)</a> <a href="z-icmp-7p.html#scrolltoc"><tt>ICMP</tt>(7P)</a> <a href="icmp-7p.html#scrolltoc"><tt>icmp</tt>(7P)</a> <a href="idn-7d.html#scrolltoc"><tt>idn</tt>(7d)</a> <a href="ieee1394-7d.html#scrolltoc"><tt>ieee1394</tt>(7D)</a> <a href="if-7p.html#scrolltoc"><tt>if</tt>(7P)</a> <a href="ifb-7d.html#scrolltoc"><tt>ifb</tt>(7d)</a> <a href="ifp-7d.html#scrolltoc"><tt>ifp</tt>(7D)</a> <a href="if-tcp-7p.html#scrolltoc"><tt>if_tcp</tt>(7P)</a> <a href="igb-7d.html#scrolltoc"><tt>igb</tt>(7D)</a> <a href="igbvf-7d.html#scrolltoc"><tt>igbvf</tt>(7D)</a> <a href="imraid-sas-7d.html#scrolltoc"><tt>imraid_sas</tt>(7D)</a> <a href="inet6-7p.html#scrolltoc"><tt>inet6</tt>(7P)</a> <a href="inet-7p.html#scrolltoc"><tt>inet</tt>(7P)</a> <a href="ip6-7p.html#scrolltoc"><tt>ip6</tt>(7P)</a> <a href="z-ip-7p.html#scrolltoc"><tt>IP</tt>(7P)</a> <a href="ip-7p.html#scrolltoc"><tt>ip</tt>(7P)</a> <a href="ipge-7d.html#scrolltoc"><tt>ipge</tt>(7D)</a> <a href="ipgpc-7ipp.html#scrolltoc"><tt>ipgpc</tt>(7ipp)</a> <a href="ipmi-7d.html#scrolltoc"><tt>ipmi</tt>(7D)</a> <a href="ipnat-7i.html#scrolltoc"><tt>ipnat</tt>(7I)</a> <a href="ipqos-7ipp.html#scrolltoc"><tt>ipqos</tt>(7ipp)</a> <a href="iprb-7d.html#scrolltoc"><tt>iprb</tt>(7D)</a> <a href="ipsec-7p.html#scrolltoc"><tt>ipsec</tt>(7P)</a> <a href="ipsecah-7p.html#scrolltoc"><tt>ipsecah</tt>(7P)</a> <a href="ipsecesp-7p.html#scrolltoc"><tt>ipsecesp</tt>(7P)</a> <a href="iscsi-7d.html#scrolltoc"><tt>iscsi</tt>(7D)</a> <a href="isdnio-7i.html#scrolltoc"><tt>isdnio</tt>(7I)</a> <a href="iser-7d.html#scrolltoc"><tt>iser</tt>(7D)</a> <a href="isp-7d.html#scrolltoc"><tt>isp</tt>(7D)</a> <a href="ixgb-7d.html#scrolltoc"><tt>ixgb</tt>(7d)</a> <a href="ixgbe-7d.html#scrolltoc"><tt>ixgbe</tt>(7D)</a> <a href="ixgbevf-7d.html#scrolltoc"><tt>ixgbevf</tt>(7D)</a> <a href="jfb-7d.html#scrolltoc"><tt>jfb</tt>(7D)</a> <a href="jfca-7d.html#scrolltoc"><tt>jfca</tt>(7D)</a> <a href="kb-7m.html#scrolltoc"><tt>kb</tt>(7M)</a> <a href="kdmouse-7d.html#scrolltoc"><tt>kdmouse</tt>(7D)</a> <a href="kfb-7d.html#scrolltoc"><tt>kfb</tt>(7D)</a> <a href="kmdb-7d.html#scrolltoc"><tt>kmdb</tt>(7d)</a> <a href="kmem-7d.html#scrolltoc"><tt>kmem</tt>(7D)</a> <a href="kstat-7d.html#scrolltoc"><tt>kstat</tt>(7D)</a> <a href="ksyms-7d.html#scrolltoc"><tt>ksyms</tt>(7D)</a> <a href="ldterm-7m.html#scrolltoc"><tt>ldterm</tt>(7M)</a> <a href="llc1-7d.html#scrolltoc"><tt>llc1</tt>(7D)</a> <a href="llc2-7d.html#scrolltoc"><tt>llc2</tt>(7D)</a> <a href="lockstat-7d.html#scrolltoc"><tt>lockstat</tt>(7D)</a> <a href="lofi-7d.html#scrolltoc"><tt>lofi</tt>(7D)</a> <a href="lofs-7fs.html#scrolltoc"><tt>lofs</tt>(7FS)</a> <a href="log-7d.html#scrolltoc"><tt>log</tt>(7D)</a> <a href="logi-7d.html#scrolltoc"><tt>logi</tt>(7D)</a> <a href="lsimega-7d.html#scrolltoc"><tt>lsimega</tt>(7D)</a> <a href="lx-systrace-7d.html#scrolltoc"><tt>lx_systrace</tt>(7D)</a> <a href="m64-7d.html#scrolltoc"><tt>m64</tt>(7D)</a> <a href="marvell88sx-7d.html#scrolltoc"><tt>marvell88sx</tt>(7D)</a> <a href="mc-opl-7d.html#scrolltoc"><tt>mc-opl</tt>(7D)</a> <a href="mcxe-7d.html#scrolltoc"><tt>mcxe</tt>(7D)</a> <a href="md-7d.html#scrolltoc"><tt>md</tt>(7D)</a> <a href="mediator-7d.html#scrolltoc"><tt>mediator</tt>(7D)</a> <a href="mega-sas-7d.html#scrolltoc"><tt>mega_sas</tt>(7D)</a> <a href="mem-7d.html#scrolltoc"><tt>mem</tt>(7D)</a> <a href="mga-7d.html#scrolltoc"><tt>mga</tt>(7D)</a> <a href="mhd-7i.html#scrolltoc"><tt>mhd</tt>(7i)</a> <a href="mixer-7i.html#scrolltoc"><tt>mixer</tt>(7I)</a> <a href="mpt-7d.html#scrolltoc"><tt>mpt</tt>(7D)</a> <a href="mpt-sas-7d.html#scrolltoc"><tt>mpt_sas</tt>(7D)</a> <a href="mr-sas-7d.html#scrolltoc"><tt>mr_sas</tt>(7D)</a> <a href="msglog-7d.html#scrolltoc"><tt>msglog</tt>(7D)</a> <a href="msm-7d.html#scrolltoc"><tt>msm</tt>(7D)</a> <a href="mt-7d.html#scrolltoc"><tt>mt</tt>(7D)</a> <a href="mtio-7i.html#scrolltoc"><tt>mtio</tt>(7I)</a> <a href="n2cp-7d.html#scrolltoc"><tt>n2cp</tt>(7d)</a> <a href="n2rng-7d.html#scrolltoc"><tt>n2rng</tt>(7d)</a> <a href="ncp-7d.html#scrolltoc"><tt>ncp</tt>(7D)</a> <a href="ncrs-7d.html#scrolltoc"><tt>ncrs</tt>(7D)</a> <a href="nfb-7d.html#scrolltoc"><tt>nfb</tt>(7D)</a> <a href="ngdr-7d.html#scrolltoc"><tt>ngdr</tt>(7d)</a> <a href="ngdrmach-7d.html#scrolltoc"><tt>ngdrmach</tt>(7d)</a> <a href="nge-7d.html#scrolltoc"><tt>nge</tt>(7D)</a> <a href="npe-7d.html#scrolltoc"><tt>npe</tt>(7D)</a> <a href="ntwdt-7d.html#scrolltoc"><tt>ntwdt</tt>(7D)</a> <a href="ntxn-7d.html#scrolltoc"><tt>ntxn</tt>(7D)</a> <a href="null-7d.html#scrolltoc"><tt>null</tt>(7D)</a> <a href="nulldriver-7d.html#scrolltoc"><tt>nulldriver</tt>(7D)</a> <a href="nv-sata-7d.html#scrolltoc"><tt>nv_sata</tt>(7D)</a> <a href="nxge-7d.html#scrolltoc"><tt>nxge</tt>(7D)</a> <a href="objfs-7fs.html#scrolltoc"><tt>objfs</tt>(7FS)</a> <a href="oce-7d.html#scrolltoc"><tt>oce</tt>(7D)</a> <a href="ocf-ibutton-7d.html#scrolltoc"><tt>ocf_ibutton</tt>(7D)</a> <a href="ohci-7d.html#scrolltoc"><tt>ohci</tt>(7D)</a> <a href="openprom-7d.html#scrolltoc"><tt>openprom</tt>(7D)</a> <a href="oplkmdrv-7d.html#scrolltoc"><tt>oplkmdrv</tt>(7D)</a> <a href="oplmsu-7d.html#scrolltoc"><tt>oplmsu</tt>(7D)</a> <a href="oplpanel-7d.html#scrolltoc"><tt>oplpanel</tt>(7D)</a> <a href="pcata-7d.html#scrolltoc"><tt>pcata</tt>(7D)</a> <a href="pcelx-7d.html#scrolltoc"><tt>pcelx</tt>(7D)</a> <a href="pcfs-7fs.html#scrolltoc"><tt>pcfs</tt>(7FS)</a> <a href="pcic-7d.html#scrolltoc"><tt>pcic</tt>(7D)</a> <a href="pcicmu-7d.html#scrolltoc"><tt>pcicmu</tt>(7D)</a> <a href="pcie-pci-7d.html#scrolltoc"><tt>pcie_pci</tt>(7D)</a> <a href="pckt-7m.html#scrolltoc"><tt>pckt</tt>(7M)</a> <a href="pcmcia-7d.html#scrolltoc"><tt>pcmcia</tt>(7D)</a> <a href="pcmem-7d.html#scrolltoc"><tt>pcmem</tt>(7D)</a> <a href="pcn-7d.html#scrolltoc"><tt>pcn</tt>(7D)</a> <a href="pcram-7d.html#scrolltoc"><tt>pcram</tt>(7D)</a> <a href="pcscsi-7d.html#scrolltoc"><tt>pcscsi</tt>(7D)</a> <a href="pcser-7d.html#scrolltoc"><tt>pcser</tt>(7D)</a> <a href="pfb-7d.html#scrolltoc"><tt>pfb</tt>(7D)</a> <a href="pf-key-7p.html#scrolltoc"><tt>pf_key</tt>(7P)</a> <a href="pfmod-7m.html#scrolltoc"><tt>pfmod</tt>(7M)</a> <a href="physmem-7d.html#scrolltoc"><tt>physmem</tt>(7D)</a> <a href="pipemod-7m.html#scrolltoc"><tt>pipemod</tt>(7M)</a> <a href="pm-7d.html#scrolltoc"><tt>pm</tt>(7D)</a> <a href="poll-7d.html#scrolltoc"><tt>poll</tt>(7d)</a> <a href="prnio-7i.html#scrolltoc"><tt>prnio</tt>(7I)</a> <a href="profile-7d.html#scrolltoc"><tt>profile</tt>(7D)</a> <a href="ptem-7m.html#scrolltoc"><tt>ptem</tt>(7M)</a> <a href="ptm-7d.html#scrolltoc"><tt>ptm</tt>(7D)</a> <a href="pts-7d.html#scrolltoc"><tt>pts</tt>(7D)</a> <a href="pty-7d.html#scrolltoc"><tt>pty</tt>(7D)</a> <a href="qfe-7d.html#scrolltoc"><tt>qfe</tt>(7d)</a> <a href="qlc-7d.html#scrolltoc"><tt>qlc</tt>(7D)</a> <a href="qlcnic-7d.html#scrolltoc"><tt>qlcnic</tt>(7D)</a> <a href="qlge-7d.html#scrolltoc"><tt>qlge</tt>(7D)</a> <a href="quotactl-7i.html#scrolltoc"><tt>quotactl</tt>(7I)</a> <a href="qus-7d.html#scrolltoc"><tt>qus</tt>(7D)</a> <a href="ramdisk-7d.html#scrolltoc"><tt>ramdisk</tt>(7D)</a> <a href="random-7d.html#scrolltoc"><tt>random</tt>(7D)</a> <a href="z-rarp-7p.html#scrolltoc"><tt>RARP</tt>(7P)</a> <a href="rarp-7p.html#scrolltoc"><tt>rarp</tt>(7P)</a> <a href="rge-7d.html#scrolltoc"><tt>rge</tt>(7D)</a> <a href="route-7p.html#scrolltoc"><tt>route</tt>(7P)</a> <a href="routing-7p.html#scrolltoc"><tt>routing</tt>(7P)</a> <a href="rtls-7d.html#scrolltoc"><tt>rtls</tt>(7D)</a> <a href="sad-7d.html#scrolltoc"><tt>sad</tt>(7D)</a> <a href="sata-7d.html#scrolltoc"><tt>sata</tt>(7D)</a> <a href="sbpro-7d.html#scrolltoc"><tt>sbpro</tt>(7D)</a> <a href="scfd-7d.html#scrolltoc"><tt>scfd</tt>(7D)</a> <a href="scmi2c-7d.html#scrolltoc"><tt>scmi2c</tt>(7d)</a> <a href="scsa1394-7d.html#scrolltoc"><tt>scsa1394</tt>(7D)</a> <a href="scsa2usb-7d.html#scrolltoc"><tt>scsa2usb</tt>(7D)</a> <a href="scsi-vhci-7d.html#scrolltoc"><tt>scsi_vhci</tt>(7D)</a> <a href="z-sctp-7p.html#scrolltoc"><tt>SCTP</tt>(7P)</a> <a href="sctp-7p.html#scrolltoc"><tt>sctp</tt>(7P)</a> <a href="scu-7d.html#scrolltoc"><tt>scu</tt>(7D)</a> <a href="sd-7d.html#scrolltoc"><tt>sd</tt>(7D)</a> <a href="sdc-7.html#scrolltoc"><tt>SDC</tt>(7)</a> <a href="sdp-7d.html#scrolltoc"><tt>sdp</tt>(7D)</a> <a href="sdt-7d.html#scrolltoc"><tt>sdt</tt>(7D)</a> <a href="se-7d.html#scrolltoc"><tt>se</tt>(7D)</a> <a href="se-hdlc-7d.html#scrolltoc"><tt>se_hdlc</tt>(7D)</a> <a href="ses-7d.html#scrolltoc"><tt>ses</tt>(7D)</a> <a href="sesio-7i.html#scrolltoc"><tt>sesio</tt>(7I)</a> <a href="sf-7d.html#scrolltoc"><tt>sf</tt>(7D)</a> <a href="sgen-7d.html#scrolltoc"><tt>sgen</tt>(7D)</a> <a href="sharefs-7fs.html#scrolltoc"><tt>sharefs</tt>(7FS)</a> <a href="si3124-7d.html#scrolltoc"><tt>si3124</tt>(7D)</a> <a href="sip-7p.html#scrolltoc"><tt>sip</tt>(7P)</a> <a href="sk98sol-7d.html#scrolltoc"><tt>sk98sol</tt>(7D)</a> <a href="skfp-7d.html#scrolltoc"><tt>skfp</tt>(7D)</a> <a href="slp-7p.html#scrolltoc"><tt>slp</tt>(7P)</a> <a href="smbios-7d.html#scrolltoc"><tt>smbios</tt>(7D)</a> <a href="smbus-7d.html#scrolltoc"><tt>smbus</tt>(7D)</a> <a href="socal-7d.html#scrolltoc"><tt>socal</tt>(7D)</a> <a href="sockio-7i.html#scrolltoc"><tt>sockio</tt>(7I)</a> <a href="sol-ofs-7d.html#scrolltoc"><tt>sol_ofs</tt>(7D)</a> <a href="sol-ucma-7d.html#scrolltoc"><tt>sol_ucma</tt>(7D)</a> <a href="sol-uverbs-7d.html#scrolltoc"><tt>sol_uverbs</tt>(7D)</a> <a href="sppptun-7m.html#scrolltoc"><tt>sppptun</tt>(7M)</a> <a href="spwr-7d.html#scrolltoc"><tt>spwr</tt>(7D)</a> <a href="ssd-7d.html#scrolltoc"><tt>ssd</tt>(7D)</a> <a href="st-7d.html#scrolltoc"><tt>st</tt>(7D)</a> <a href="stp4020-7d.html#scrolltoc"><tt>stp4020</tt>(7D)</a> <a href="streamio-7i.html#scrolltoc"><tt>streamio</tt>(7I)</a> <a href="su-7d.html#scrolltoc"><tt>su</tt>(7D)</a> <a href="sxge-7d.html#scrolltoc"><tt>sxge</tt>(7D)</a> <a href="sxp-7d.html#scrolltoc"><tt>sxp</tt>(7D)</a> <a href="symhisl-7d.html#scrolltoc"><tt>symhisl</tt>(7D)</a> <a href="sysmsg-7d.html#scrolltoc"><tt>sysmsg</tt>(7D)</a> <a href="systrace-7d.html#scrolltoc"><tt>systrace</tt>(7D)</a> <a href="tavor-7d.html#scrolltoc"><tt>tavor</tt>(7D)</a> <a href="z-tcp-7p.html#scrolltoc"><tt>TCP</tt>(7P)</a> <a href="tcp-7p.html#scrolltoc"><tt>tcp</tt>(7P)</a> <a href="termio-7i.html#scrolltoc"><tt>termio</tt>(7I)</a> <a href="termiox-7i.html#scrolltoc"><tt>termiox</tt>(7I)</a> <a href="ticlts-7d.html#scrolltoc"><tt>ticlts</tt>(7D)</a> <a href="ticots-7d.html#scrolltoc"><tt>ticots</tt>(7D)</a> <a href="ticotsord-7d.html#scrolltoc"><tt>ticotsord</tt>(7D)</a> <a href="timod-7m.html#scrolltoc"><tt>timod</tt>(7M)</a> <a href="tirdwr-7m.html#scrolltoc"><tt>tirdwr</tt>(7M)</a> <a href="tmpfs-7fs.html#scrolltoc"><tt>tmpfs</tt>(7FS)</a> <a href="todopl-7d.html#scrolltoc"><tt>todopl</tt>(7D)</a> <a href="tokenmt-7ipp.html#scrolltoc"><tt>tokenmt</tt>(7ipp)</a> <a href="tpf-7d.html#scrolltoc"><tt>tpf</tt>(7D)</a> <a href="tsalarm-7d.html#scrolltoc"><tt>tsalarm</tt>(7D)</a> <a href="tswtclmt-7ipp.html#scrolltoc"><tt>tswtclmt</tt>(7ipp)</a> <a href="ttcompat-7m.html#scrolltoc"><tt>ttcompat</tt>(7M)</a> <a href="tty-7d.html#scrolltoc"><tt>tty</tt>(7D)</a> <a href="ttymux-7d.html#scrolltoc"><tt>ttymux</tt>(7D)</a> <a href="tun-7m.html#scrolltoc"><tt>tun</tt>(7M)</a> <a href="tzmon-7d.html#scrolltoc"><tt>tzmon</tt>(7d)</a> <a href="uata-7d.html#scrolltoc"><tt>uata</tt>(7D)</a> <a href="udfs-7fs.html#scrolltoc"><tt>udfs</tt>(7FS)</a> <a href="z-udp-7p.html#scrolltoc"><tt>UDP</tt>(7P)</a> <a href="udp-7p.html#scrolltoc"><tt>udp</tt>(7P)</a> <a href="ufs-7fs.html#scrolltoc"><tt>ufs</tt>(7FS)</a> <a href="ugen-7d.html#scrolltoc"><tt>ugen</tt>(7D)</a> <a href="uhci-7d.html#scrolltoc"><tt>uhci</tt>(7D)</a> <a href="urandom-7d.html#scrolltoc"><tt>urandom</tt>(7D)</a> <a href="usb-7d.html#scrolltoc"><tt>usb</tt>(7D)</a> <a href="usba-7d.html#scrolltoc"><tt>usba</tt>(7D)</a> <a href="usb-ac-7d.html#scrolltoc"><tt>usb_ac</tt>(7D)</a> <a href="usb-ah-7m.html#scrolltoc"><tt>usb_ah</tt>(7M)</a> <a href="usb-as-7d.html#scrolltoc"><tt>usb_as</tt>(7D)</a> <a href="usbecm-7d.html#scrolltoc"><tt>usbecm</tt>(7D)</a> <a href="usbkbm-7m.html#scrolltoc"><tt>usbkbm</tt>(7M)</a> <a href="usb-mid-7d.html#scrolltoc"><tt>usb_mid</tt>(7D)</a> <a href="usbms-7m.html#scrolltoc"><tt>usbms</tt>(7M)</a> <a href="usbprn-7d.html#scrolltoc"><tt>usbprn</tt>(7D)</a> <a href="usbsacm-7d.html#scrolltoc"><tt>usbsacm</tt>(7D)</a> <a href="usbser-edge-7d.html#scrolltoc"><tt>usbser_edge</tt>(7D)</a> <a href="usbsksp-7d.html#scrolltoc"><tt>usbsksp</tt>(7D)</a> <a href="usbsprl-7d.html#scrolltoc"><tt>usbsprl</tt>(7D)</a> <a href="uscsi-7i.html#scrolltoc"><tt>uscsi</tt>(7I)</a> <a href="usoc-7d.html#scrolltoc"><tt>usoc</tt>(7D)</a> <a href="virtualkm-7d.html#scrolltoc"><tt>virtualkm</tt>(7D)</a> <a href="visual-io-7i.html#scrolltoc"><tt>visual_io</tt>(7I)</a> <a href="vni-7d.html#scrolltoc"><tt>vni</tt>(7d)</a> <a href="volfs-7fs.html#scrolltoc"><tt>volfs</tt>(7FS)</a> <a href="vuid2ps2-7m.html#scrolltoc"><tt>vuid2ps2</tt>(7M)</a> <a href="vuid3ps2-7m.html#scrolltoc"><tt>vuid3ps2</tt>(7M)</a> <a href="vuidm3p-7m.html#scrolltoc"><tt>vuidm3p</tt>(7M)</a> <a href="vuidm4p-7m.html#scrolltoc"><tt>vuidm4p</tt>(7M)</a> <a href="vuidm5p-7m.html#scrolltoc"><tt>vuidm5p</tt>(7M)</a> <a href="vuidmice-7m.html#scrolltoc"><tt>vuidmice</tt>(7M)</a> <a href="wrsm-7d.html#scrolltoc"><tt>wrsm</tt>(7D)</a> <a href="wrsmd-7d.html#scrolltoc"><tt>wrsmd</tt>(7D)</a> <a href="wscons-7d.html#scrolltoc"><tt>wscons</tt>(7D)</a> <a href="xge-7d.html#scrolltoc"><tt>xge</tt>(7D)</a> <a href="xhci-7d.html#scrolltoc"><tt>xhci</tt>(7D)</a> <a href="xmemfs-7fs.html#scrolltoc"><tt>xmemfs</tt>(7FS)</a> <a href="zcons-7d.html#scrolltoc"><tt>zcons</tt>(7D)</a> <a href="zero-7d.html#scrolltoc"><tt>zero</tt>(7D)</a> <a href="zs-7d.html#scrolltoc"><tt>zs</tt>(7D)</a> <a href="zsh-7d.html#scrolltoc"><tt>zsh</tt>(7D)</a> <a href="zulu-7d.html#scrolltoc"><tt>zulu</tt>(7d)</a> </div> <a name="REFMAN7content"></a><a name="content"></a> <div class="ContentPane"> <a name="REFMAN7audio-7i"></a><a name="audio-7i"></a><h3>audio</h3> - generic audio device interface<h3>Synopsis</h3> <pre><tt>#include</tt> <tt><sys/audio.h></tt> </pre><h2>OVERVIEW</h2> An audio device is used to play and/or record a stream of audio data. Since a specific audio device may not support all functionality described below, refer to the device-specific manual pages for a complete description of each hardware device. An application can use the <tt>AUDIO_GETDEV</tt> <a href="../816-5167/ioctl-2.html#REFMAN2ioctl-2"><tt>ioctl</tt>(2)</a> to determine the current audio hardware associated with <tt>/dev/audio</tt>. <h2>AUDIO FORMATS</h2> Digital audio data represents a quantized approximation of an analog audio signal waveform. In the simplest case, these quantized numbers represent the amplitude of the input waveform at particular sampling intervals. To achieve the best approximation of an input signal, the highest possible sampling frequency and precision should be used. However, increased accuracy comes at a cost of increased data storage requirements. For instance, one minute of monaural audio recorded in µ-Law format (pronounced mew-law) at 8 KHz requires nearly 0.5 megabytes of storage, while the standard Compact Disc audio format (stereo 16-bit linear PCM data sampled at 44.1 KHz) requires approximately 10 megabytes per minute.Audio data may be represented in several different formats. An audio device's current audio data format can be determined by using the <tt>AUDIO_GETINFO</tt> <a href="../816-5167/ioctl-2.html#REFMAN2ioctl-2"><tt>ioctl</tt>(2)</a> described below.An audio data format is characterized in the audio driver by four parameters: Sample Rate, Encoding, Precision, and Channels. Refer to the device-specific manual pages for a list of the audio formats that each device supports. In addition to the formats that the audio device supports directly, other formats provide higher data compression. Applications may convert audio data to and from these formats when playing or recording.<h3>Sample Rate</h3> Sample rate is a number that represents the sampling frequency (in samples per second) of the audio data.<h3>Encodings</h3> An encoding parameter specifies the audio data representation. µ-Law encoding corresponds to CCITT G.711, and is the standard for voice data used by telephone companies in the United States, Canada, and Japan. A-Law encoding is also part of CCITT G.711 and is the standard encoding for telephony elsewhere in the world. A-Law and µ-Law audio data are sampled at a rate of 8000 samples per second with 12-bit precision, with the data compressed to 8-bit samples. The resulting audio data quality is equivalent to that of standard analog telephone service.Linear Pulse Code Modulation (PCM) is an uncompressed, signed audio format in which sample values are directly proportional to audio signal voltages. Each sample is a 2's complement number that represents a positive or negative amplitude.<h3>Precision</h3> Precision indicates the number of bits used to store each audio sample. For instance, u-Law and A-Law data are stored with 8-bit precision. PCM data may be stored at various precisions, though 16-bit is the most common.<h3>Channels</h3> Multiple channels of audio may be interleaved at sample boundaries. A sample frame consists of a single sample from each active channel. For example, a sample frame of stereo 16-bit PCM data consists of 2 16-bit samples, corresponding to the left and right channel data.<h2>Description</h2> The device <tt>/dev/audio</tt> is a device driver that dispatches audio requests to the appropriate underlying audio hardware. The audio driver is implemented as a STREAMS driver. In order to record audio input, applications <a href="../816-5167/open-2.html#REFMAN2open-2"><tt>open</tt>(2)</a> the <tt>/dev/audio</tt> device and read data from it using the <a href="../816-5167/read-2.html#REFMAN2read-2"><tt>read</tt>(2)</a> system call. Similarly, sound data is queued to the audio output port by using the <a href="../816-5167/write-2.html#REFMAN2write-2"><tt>write</tt>(2)</a> system call. Device configuration is performed using the <a href="../816-5167/ioctl-2.html#REFMAN2ioctl-2"><tt>ioctl</tt>(2)</a> interface.Alternatively, opening <tt>/dev/audio</tt> may open a mixing audio driver that provides a super set of this audio interface. The audio mixer removes the exclusive resource restriction, allowing multiple processes to play and record audio at the same time. See the <a href="mixer-7i.html#scrolltoc"><tt>mixer</tt>(7I)</a> and <a href="audio-support-7i.html#scrolltoc"><tt>audio_support</tt>(7I)</a> manual pages for more information.Because some systems may contain more than one audio device, application writers are encouraged to query the <tt>AUDIODEV</tt> environment variable. If this variable is present in the environment, its value should identify the path name of the default audio device.<h3>Opening the Audio Device</h3> The audio device is treated as an exclusive resource, meaning that only one process can open the device at a time. However, if the <tt>DUPLEX</tt> bit is set in the <tt>hw_features</tt> field of the audio information structure, two processes may simultaneously access the device. This allows one process to open the device as read-only and a second process to open it as write-only. See below for details.When a process cannot open <tt>/dev/audio</tt> because the device is busy: <ul><li>if either the <tt>O_NDELAY</tt> or <tt>O_NONBLOCK</tt> flags are set in the <tt>open()</tt> <var>oflag</var> argument, then –1 is immediately returned, with <var>errno</var> set to <tt>EBUSY.</tt> </li> <li>if neither the <tt>O_NDELAY</tt> nor the <tt>O_NONBLOCK</tt> flag are set, then <tt>open()</tt> hangs until the device is available or a signal is delivered to the process, in which case a –1 is returned with <var>errno</var> set to <tt>EINTR.</tt> This allows a process to block in the <tt>open</tt> call while waiting for the audio device to become available.</li></ul> Upon the initial <tt>open()</tt> of the audio device, the driver resets the data format of the device to the default state of 8-bit, 8Khz, mono u-Law data. If the device is already open and a different audio format is set, this will not be possible on some devices. With the exception of some devices that only support a limited number of sample rates, audio applications should explicitly set the encoding characteristics to match the audio data requirements rather than depend on the default configuration.Since the audio device grants exclusive read or write access to a single process at a time, long-lived audio applications may choose to close the device when they enter an idle state and reopen it when required. The <var>play.waiting</var> and <var>record.waiting</var> flags in the audio information structure (see below) provide an indication that another process has requested access to the device. For instance, a background audio output process may choose to relinquish the audio device whenever another process requests write access.<h3>Recording Audio Data</h3> The <tt>read()</tt> system call copies data from the system's buffers to the application. Ordinarily, <tt>read()</tt> blocks until the user buffer is filled. The <tt>I_NREAD</tt> <tt>ioctl</tt> (see <a href="streamio-7i.html#scrolltoc"><tt>streamio</tt>(7I)</a>) may be used to determine the amount of data that may be read without blocking. The device may alternatively be set to a non-blocking mode, in which case <tt>read()</tt> completes immediately, but may return fewer bytes than requested. Refer to the <a href="../816-5167/read-2.html#REFMAN2read-2"><tt>read</tt>(2)</a> manual page for a complete description of this behavior.When the audio device is opened with read access, the device driver immediately starts buffering audio input data. Since this consumes system resources, processes that do not record audio data should open the device write-only (<tt>O_WRONLY</tt>).The transfer of input data to STREAMS buffers may be paused (or resumed) by using the <tt>AUDIO_SETINFO</tt> <tt>ioctl</tt> to set (or clear) the <var>record.pause</var> flag in the audio information structure (see below). All unread input data in the STREAMS queue may be discarded by using the <tt>I_FLUSH</tt> STREAMS <tt>ioctl</tt> (see <a href="streamio-7i.html#scrolltoc"><tt>streamio</tt>(7I)</a>). When changing record parameters, the input stream should be paused and flushed before the change, and resumed afterward. Otherwise, subsequent reads may return samples in the old format followed by samples in the new format. This is particularly important when new parameters result in a changed sample size.Input data can accumulate in STREAMS buffers very quickly. At a minimum, it will accumulate at 8000 bytes per second for 8-bit, 8 KHz, mono, u-Law data. If the device is configured for 16-bit linear or higher sample rates, it will accumulate even faster. If the application that consumes the data cannot keep up with this data rate, the STREAMS queue may become full. When this occurs, the <var>record.error</var> flag is set in the audio information structure and input sampling ceases until there is room in the input queue for additional data. In such cases, the input data stream contains a discontinuity. For this reason, audio recording applications should open the audio device when they are prepared to begin reading data, rather than at the start of extensive initialization.<h3>Playing Audio Data</h3> The <tt>write()</tt> system call copies data from an application's buffer to the STREAMS output queue. Ordinarily, <tt>write()</tt> blocks until the entire user buffer is transferred. The device may alternatively be set to a non-blocking mode, in which case <tt>write()</tt> completes immediately, but may have transferred fewer bytes than requested (see <a href="../816-5167/write-2.html#REFMAN2write-2"><tt>write</tt>(2)</a>). Although <tt>write()</tt> returns when the data is successfully queued, the actual completion of audio output may take considerably longer. The <tt>AUDIO_DRAIN</tt> <tt>ioctl</tt> may be issued to allow an application to block until all of the queued output data has been played. Alternatively, a process may request asynchronous notification of output completion by writing a zero-length buffer (end-of-file record) to the output stream. When such a buffer has been processed, the <var>play.eof</var> flag in the audio information structure (see below) is incremented.The final <a href="../816-5167/close-2.html#REFMAN2close-2"><tt>close</tt>(2)</a> of the file descriptor hangs until all of the audio output has drained. If a signal interrupts the <tt>close()</tt>, or if the process exits without closing the device, any remaining data queued for audio output is flushed and the device is closed immediately.The consumption of output data may be paused (or resumed) by using the <tt>AUDIO_SETINFO</tt> <tt>ioctl</tt> to set (or clear) the <var>play.pause</var> flag in the audio information structure. Queued output data may be discarded by using the <tt>I_FLUSH</tt> STREAMS <tt>ioctl</tt>. (See <a href="streamio-7i.html#scrolltoc"><tt>streamio</tt>(7I)</a>).Output data is played from the STREAMS buffers at a default rate of at least 8000 bytes per second for µ-Law, A-Law or 8–bit PCM data (faster for 16-bit linear data or higher sampling rates). If the output queue becomes empty, the <var>play.error</var> flag is set in the audio information structure and output is stopped until additional data is written. If an application attempts to write a number of bytes that is not a multiple of the current sample frame size, an error is generated and the bad data is thrown away. Additional writes are allowed.<h3>Asynchronous I/O</h3> The <tt>I_SETSIG</tt> STREAMS <tt>ioctl</tt> enables asynchronous notification, through the <tt>SIGPOLL</tt> signal, of input and output ready condition changes. The <tt>O_NONBLOCK</tt> flag may be set using the <tt>F_SETFL</tt> <a href="../816-5167/fcntl-2.html#REFMAN2fcntl-2"><tt>fcntl</tt>(2)</a> to enable non-blocking <tt>read()</tt> and <tt>write()</tt> requests. This is normally sufficient for applications to maintain an audio stream in the background.<h3>Audio Control Pseudo-Device</h3> It is sometimes convenient to have an application, such as a volume control panel, modify certain characteristics of the audio device while it is being used by an unrelated process. The <tt>/dev/audioctl</tt> pseudo-device is provided for this purpose. Any number of processes may open <tt>/dev/audioctl</tt> simultaneously. However, <tt>read()</tt> and <tt>write()</tt> system calls are ignored by <tt>/dev/audioctl</tt>. The <tt>AUDIO_GETINFO</tt> and <tt>AUDIO_SETINFO</tt> <tt>ioctl</tt> commands may be issued to <tt>/dev/audioctl</tt> to determine the status or alter the behavior of <tt>/dev/audio</tt>. Note: In general, the audio control device name is constructed by appending the letters <tt>"ctl"</tt> to the path name of the audio device.<h3>Audio Status Change Notification</h3> Applications that open the audio control pseudo-device may request asynchronous notification of changes in the state of the audio device by setting the <tt>S_MSG</tt> flag in an <tt>I_SETSIG</tt> STREAMS <tt>ioctl</tt>. Such processes receive a <tt>SIGPOLL</tt> signal when any of the following events occur: <ul><li>An <tt>AUDIO_SETINFO</tt> <tt>ioctl</tt> has altered the device state.</li> <li>An input overflow or output underflow has occurred.</li> <li>An end-of-file record (zero-length buffer) has been processed on output.</li> <li>An <tt>open()</tt> or <tt>close()</tt> of <tt>/dev/audio</tt> has altered the device state.</li> <li>An external event (such as speakerbox's volume control) has altered the device state.</li></ul> <h2>ioctls</h2> <h3>Audio Information Structure</h3> The state of the audio device may be polled or modified using the <tt>AUDIO_GETINFO</tt> and <tt>AUDIO_SETINFO</tt> <tt>ioctl</tt> commands. These commands operate on the <tt>audio_info</tt> structure as defined, in <tt><sys/audio.h></tt>, as follows:<pre>/* * This structure contains state information for audio device * IO streams */ struct audio_prinfo { /* * The following values describe the * audio data encoding */ uint_t sample_rate; /* samples per second */ uint_t channels; /* number of interleaved channels */ uint_t precision; /* number of bits per sample */ uint_t encoding; /* data encoding method */ /* * The following values control audio device * configuration */ uint_t gain; /* volume level */ uint_t port; /* selected I/O port */ uint_t buffer_size; /* I/O buffer size */ /* * The following values describe the current device * state */ uint_t samples; /* number of samples converted */ uint_t eof; /* End Of File counter (play only) */ uchar_t pause; /* non-zero if paused, zero to resume */ uchar_t error; /* non-zero if overflow/underflow */ uchar_t waiting; /* non-zero if a process wants access */ uchar_t balance; /* stereo channel balance */ /* * The following values are read-only device state * information */ uchar_t open; /* non-zero if open access granted */ uchar_t active; /* non-zero if I/O active */ uint_t avail_ports; /* available I/O ports */ uint_t mod_ports; /* modifiable I/O ports */ }; typedef struct audio_prinfo audio_prinfo_t; /* * This structure is used in AUDIO_GETINFO and AUDIO_SETINFO ioctl * commands */ struct audio_info { audio_prinfo_t record; /* input status info */ audio_prinfo_t play; /* output status info */ uint_t monitor_gain; /* input to output mix */ uchar_t output_muted; /* non-zero if output muted */ uint_t hw_features; /* supported H/W features */ uint_t sw_features; /* supported S/W features */ uint_t sw_features_enabled; /* supported S/W features enabled */ }; typedef struct audio_info audio_info_t; /* Audio encoding types */ #define AUDIO_ENCODING_ULAW (1) /* u-Law encoding */ #define AUDIO_ENCODING_ALAW (2) /* A-Law encoding */ #define AUDIO_ENCODING_LINEAR (3) /* Signed Linear PCM encoding */ /* * These ranges apply to record, play, and * monitor gain values */ #define AUDIO_MIN_GAIN (0) /* minimum gain value */ #define AUDIO_MAX_GAIN (255) /* maximum gain value */ /* * These values apply to the balance field to adjust channel * gain values */ #define AUDIO_LEFT_BALANCE (0) /* left channel only */ #define AUDIO_MID_BALANCE (32) /* equal left/right balance */ #define AUDIO_RIGHT_BALANCE (64) /* right channel only */ /* * Define some convenient audio port names * (for port, avail_ports and mod_ports) */ /* output ports (several might be enabled at once) */ #define AUDIO_SPEAKER (0x01) /* built-in speaker */ #define AUDIO_HEADPHONE (0x02) /* headphone jack */ #define AUDIO_LINE_OUT (0x04) /* line out */ #define AUDIO_SPDIF_OUT (0x08) /* SPDIF port */ #define AUDIO_AUX1_OUT (0x10) /* aux1 out */ #define AUDIO_AUX2_OUT (0x20) /* aux2 out */ /* input ports (usually only one may be * enabled at a time) */ #define AUDIO_MICROPHONE (0x01) /* microphone */ #define AUDIO_LINE_IN (0x02) /* line in */ #define AUDIO_CD (0x04) /* on-board CD inputs */ #define AUDIO_SPDIF_IN (0x08) /* SPDIF port */ #define AUDIO_AUX1_IN (0x10) /* aux1 in */ #define AUDIO_AUX2_IN (0x20) /* aux2 in */ #define AUDIO_CODEC_LOOPB_IN (0x40) /* Codec inter.loopback */ /* These defines are for hardware features */ #define AUDIO_HWFEATURE_DUPLEX (0x00000001u) /*simult. play & cap. supported */ #define AUDIO_HWFEATURE_MSCODEC (0x00000002u) /* multi-stream Codec */ /* These defines are for software features * #define AUDIO_SWFEATURE_MIXER (0x00000001u) /* audio mixer audio pers. mod. */ /* * Parameter for the AUDIO_GETDEV ioctl * to determine current audio devices */ #define MAX_AUDIO_DEV_LEN (16) struct audio_device { char name[MAX_AUDIO_DEV_LEN]; char version[MAX_AUDIO_DEV_LEN]; char config[MAX_AUDIO_DEV_LEN]; }; typedef struct audio_device audio_device_t;</pre>The <var>play.gain</var> and <var>record.gain</var> fields specify the output and input volume levels. A value of <tt>AUDIO_MAX_GAIN</tt> indicates maximum volume. Audio output may also be temporarily muted by setting a non-zero value in the <var>output_muted</var> field. Clearing this field restores audio output to the normal state. Most audio devices allow input data to be monitored by mixing audio input onto the output channel. The <var>monitor_gain</var> field controls the level of this feedback path.The <var>play.port</var> field controls the output path for the audio device. It can be set to either <tt>AUDIO_SPEAKER</tt> (built-in speaker), <tt>AUDIO_HEADPHONE</tt> (headphone jack), <tt>AUDIO_LINE_OUT</tt> (line-out port), <tt>AUDIO_AUX1_OUT</tt> (auxilary1 out), or <tt>AUDIO_AUX2_OUT</tt> (auxilary2 out). For some devices, it may be set to a combination of these ports. The <var>play.avail_ports</var> field returns the set of output ports that are currently accessible. The <var>play.mod_ports</var> field returns the set of output ports that may be turned on and off. If a port is missing from <var>play.mod_ports</var> then that port is assumed to always be on.The <var>record.port</var> field controls the input path for the audio device. It can be either <tt>AUDIO_MICROPHONE</tt> (microphone jack), <tt>AUDIO_LINE_IN</tt> (line-out port), <tt>AUDIO_CD</tt> (internal CD-ROM), <tt>AUDIO_AUX1_IN</tt> (auxilary1 in), <tt>AUDIO_AUX2_IN</tt> (auxilary2 in), or <tt>AUDIO_CODEC_LOOPB_IN</tt> (internal loopback). The <var>record.avail_ports</var> field returns the set of input ports that are currently accessible. The <var>record.mod_ports</var> field returns the set of input ports that may be turned on and off. If a port is missing from <var>record.mod_ports</var>, it is assumed to always be on. Input ports are considered to be mutually exclusive.The <var>play.balance</var> and <var>record.balance</var> fields are used to control the volume between the left and right channels when manipulating stereo data. When the value is set between <tt>AUDIO_LEFT_BALANCE</tt> and <tt>AUDIO_MID_BALANCE</tt>, the right channel volume will be reduced in proportion to the <var>balance</var> value. Conversely, when <var>balance</var> is set between <tt>AUDIO_MID_BALANCE</tt> and <tt>AUDIO_RIGHT_BALANCE</tt>, the left channel will be proportionally reduced.The <var>play.pause</var> and <var>record.pause</var> flags may be used to pause and resume the transfer of data between the audio device and the STREAMS buffers. The <var>play.error</var> and <var>record.error</var> flags indicate that data underflow or overflow has occurred. The <var>play.active</var> and <var>record.active</var> flags indicate that data transfer is currently active in the corresponding direction.The <var>play.open</var> and <var>record.open</var> flags indicate that the device is currently open with the corresponding access permission. The <var>play.waiting</var> and <var>record.waiting</var> flags provide an indication that a process may be waiting to access the device. These flags are set automatically when a process blocks on <tt>open()</tt>, though they may also be set using the <tt>AUDIO_SETINFO</tt> <tt>ioctl</tt> command. They are cleared only when a process relinquishes access by closing the device.The <var>play.samples</var> and <var>record.samples</var> fields are zeroed at <tt>open()</tt> and are incremented each time a data sample is copied to or from the associated STREAMS queue. Some audio drivers may be limited to counting buffers of samples, instead of single samples for their <var>samples</var> accounting. For this reason, applications should not assume that the <var>samples</var> fields contain a perfectly accurate count. The <var>play.eof</var> field increments whenever a zero-length output buffer is synchronously processed. Applications may use this field to detect the completion of particular segments of audio output.The <var>record.buffer_size</var> field controls the amount of input data that is buffered in the device driver during record operations. Applications that have particular requirements for low latency should set the value appropriately. Note however that smaller input buffer sizes may result in higher system overhead. The value of this field is specified in bytes and drivers will constrain it to be a multiple of the current sample frame size. Some drivers may place other requirements on the value of this field. Refer to the audio device-specific manual page for more details. If an application changes the format of the audio device and does not modify the <var>record.buffer_size</var> field, the device driver may use a default value to compensate for the new data rate. Therefore, if an application is going to modify this field, it should modify it during or after the format change itself, not before. When changing the <var>record.buffer_size</var> parameters, the input stream should be paused and flushed before the change, and resumed afterward. Otherwise, subsequent reads may return samples in the old format followed by samples in the new format. This is particularly important when new parameters result in a changed sample size. If you change the <var>record.buffer_size</var> for the first packet, this protocol must be followed or the first buffer will be the default buffer size for the device, followed by packets of the requested change size.The <var>record.buffer_size</var> field may be modified only on the <tt>/dev/audio</tt> device by processes that have it opened for reading. The <var>play.buffer_size</var> field is currently not supported.The audio data format is indicated by the <var>sample_rate</var>, <var>channels</var>, <var>precision</var>, and <var>encoding</var> fields. The values of these fields correspond to the descriptions in the <tt>AUDIO</tt> <tt>FORMATS</tt> section above. Refer to the audio device-specific manual pages for a list of supported data format combinations.The data format fields may be modified only on the <tt>/dev/audio</tt> device. Some audio hardware may constrain the input and output data formats to be identical. If this is the case, the data format may not be changed if multiple processes have opened the audio device. As a result, a process should check that the <tt>ioctl()</tt> does not fail when it attempts to set the data format.If the parameter changes requested by an <tt>AUDIO_SETINFO</tt> <tt>ioctl</tt> cannot all be accommodated, <tt>ioctl()</tt> will return with <var>errno</var> set to <tt>EINVAL</tt> and no changes will be made to the device state.<h3>Streamio IOCTLS</h3> All of the <a href="streamio-7i.html#scrolltoc"><tt>streamio</tt>(7I)</a> <tt>ioctl</tt> commands may be issued for the <tt>/dev/audio</tt> device. Because the <tt>/dev/audioctl</tt> device has its own STREAMS queues, most of these commands neither modify nor report the state of <tt>/dev/audio</tt> if issued for the <tt>/dev/audioctl</tt> device. The <tt>I_SETSIG</tt> <tt>ioctl</tt> may be issued for <tt>/dev/audioctl</tt> to enable the notification of audio status changes, as described above.<h3>Audio IOCTLS</h3> The audio device additionally supports the following <tt>ioctl</tt> commands:<dl><dt><tt>AUDIO_DRAIN</tt></dt> <dd>The argument is ignored. This command suspends the calling process until the output STREAMS queue is empty, or until a signal is delivered to the calling process. It may not be issued for the <tt>/dev/audioctl</tt> device. An implicit <tt>AUDIO_DRAIN</tt> is performed on the final <tt>close()</tt> of <tt>/dev/audio</tt>. </dd> <dt><tt>AUDIO_GETDEV</tt></dt> <dd>The argument is a pointer to an <tt>audio_device_t</tt> structure. This command may be issued for either <tt>/dev/audio</tt> or <tt>/dev/audioctl</tt>. The returned value in the <var>name</var> field will be a string that will identify the current <tt>/dev/audio</tt> hardware device, the value in <var>version</var> will be a string indicating the current version of the hardware, and <var>config</var> will be a device-specific string identifying the properties of the audio stream associated with that file descriptor. Refer to the audio device-specific manual pages to determine the actual strings returned by the device driver.</dd> <dt><tt>AUDIO_GETINFO</tt></dt> <dd>The argument is a pointer to an <tt>audio_info_t</tt> structure. This command may be issued for either <tt>/dev/audio</tt> or <tt>/dev/audioctl</tt>. The current state of the <tt>/dev/audio</tt> device is returned in the structure.</dd> <dt><tt>AUDIO_SETINFO</tt></dt> <dd>The argument is a pointer to an <tt>audio_info_t</tt> structure. This command may be issued for either the <tt>/dev/audio</tt> or the <tt>/dev/audioctl</tt> device with some restrictions. This command configures the audio device according to the supplied structure and overwrites the existing structure with the new state of the device. Note: The <var>play.samples</var>, <var>record.samples</var>, <var>play.error</var>, <var>record.error</var>, and <var>play.eof</var> fields are modified to reflect the state of the device when the <tt>AUDIO_SETINFO</tt> is issued. This allows programs to automatically modify these fields while retrieving the previous value.</dd> </dl> Certain fields in the audio information structure, such as the <var>pause</var> flags, are treated as read-only when <tt>/dev/audio</tt> is not open with the corresponding access permission. Other fields, such as the gain levels and encoding information, may have a restricted set of acceptable values. Applications that attempt to modify such fields should check the returned values to be sure that the corresponding change took effect. The <var>sample_rate</var>, <var>channels</var>, <var>precision</var>, and <var>encoding</var> fields treated as read-only for <tt>/dev/audioctl</tt>, so that applications can be guaranteed that the existing audio format will stay in place until they relinquish the audio device. <tt>AUDIO_SETINFO</tt> will return EINVAL when the desired configuration is not possible, or EBUSY when another process has control of the audio device.Once set, the following values persist through subsequent <tt>open()</tt> and <tt>close()</tt> calls of the device and automatic device unloads: <var>play.gain</var>, <var>record.gain</var>, <var>play.balance</var>, <var>record.balance</var>, <var>play.port</var>, <var>record.port</var>, <var>monitor_gain</var> and <var>output_muted</var>. For the <tt>dbri</tt> driver, an automatic device driver unload resets these parameters to their default values on the next load. All other state is reset when the corresponding I/O stream of <tt>/dev/audio</tt> is closed.The <tt>audio_info_t</tt> structure may be initialized through the use of the <tt>AUDIO_INITINFO</tt> macro. This macro sets all fields in the structure to values that are ignored by the <tt>AUDIO_SETINFO</tt> command. For instance, the following code switches the output port from the built-in speaker to the headphone jack without modifying any other audio parameters:<pre>audio_info_t info; AUDIO_INITINFO(&info); info.play.port = AUDIO_HEADPHONE; err = ioctl(audio_fd, AUDIO_SETINFO, &info);</pre>This technique eliminates problems associated with using a sequence of <tt>AUDIO_GETINFO</tt> followed by <tt>AUDIO_SETINFO</tt>. <h2>Errors</h2> An <tt>open()</tt> will fail if:<dl><dt><tt>EBUSY</tt></dt> <dd>The requested play or record access is busy and either the <tt>O_NDELAY</tt> or <tt>O_NONBLOCK</tt> flag was set in the <tt>open()</tt> request.</dd> <dt><tt>EINTR</tt></dt> <dd>The requested play or record access is busy and a signal interrupted the <tt>open()</tt> request.</dd> </dl> An <tt>ioctl()</tt> will fail if:<dl><dt><tt>EINVAL</tt></dt> <dd>The parameter changes requested in the <tt>AUDIO_SETINFO</tt> <tt>ioctl</tt> are invalid or are not supported by the device.</dd> <dt><tt>EBUSY</tt></dt> <dd>The parameter changes requested in the <tt>AUDIO_SETINFO</tt> <tt>ioctl</tt> could not be made because another process has the device open and is using a different format.</dd> </dl> <h2>Files</h2> The physical audio device names are system dependent and are rarely used by programmers. Programmers should use the generic device names listed below.<dl><dt><tt>/dev/audio</tt></dt> <dd>symbolic link to the system's primary audio device</dd> <dt><tt>/dev/audioctl</tt></dt> <dd>symbolic link to the control device for <tt>/dev/audio</tt> </dd> <dt><tt>/dev/sound/0</tt></dt> <dd>first audio device in the system</dd> <dt><tt>/dev/sound/0ctl</tt></dt> <dd>audio control device for <tt>/dev/sound/0</tt> </dd> <dt><tt>/usr/share/audio/samples</tt></dt> <dd>audio files</dd> </dl> <h2>Attributes</h2> See <a href="../816-5175/attributes-5.html#REFMAN5attributes-5"><tt>attributes</tt>(5)</a> for a description of the following attributes: <table datatable="0" border="0" cellpadding="0" cellspacing="0" class="dkgrey1" width="100%"> <tr><td><table summary="" datatable="1" border="0" cellpadding="0" cellspacing="1" width="100%" class="vatop"><col width="33%"><col width="66%"><tr><th scope="col" class="columncaption" align="center" valign="top"><div class="headerpadding">ATTRIBUTE TYPE</div></th> <th scope="col" class="columncaption" align="center" valign="top"><div class="headerpadding">ATTRIBUTE VALUE</div></th> </tr> <tr class="yellow2"> <td scope="row" align="left" valign="top"><div class="pad5x10">Architecture</div></td> <td align="left" valign="top"><div class="pad5x10">SPARC, x86</div></td> </tr> <tr class="yellow2"> <td scope="row" align="left" valign="top"><div class="pad5x10">Availability</div></td> <td align="left" valign="top"><div class="pad5x10">SUNWcsu, SUNWcsxu, SUNWaudd, SUNWauddx, SUNWaudh</div></td> </tr> <tr class="yellow2"> <td scope="row" align="left" valign="top"><div class="pad5x10">Stability Level</div></td> <td align="left" valign="top"><div class="pad5x10">Evolving</div></td> </tr> </table> </td></tr></table> <h2>See Also</h2> <a href="../816-5167/close-2.html#REFMAN2close-2"><tt>close</tt>(2)</a>, <a href="../816-5167/fcntl-2.html#REFMAN2fcntl-2"><tt>fcntl</tt>(2)</a>, <a href="../816-5167/ioctl-2.html#REFMAN2ioctl-2"><tt>ioctl</tt>(2)</a>, <a href="../816-5167/open-2.html#REFMAN2open-2"><tt>open</tt>(2)</a>, <a href="../816-5167/poll-2.html#REFMAN2poll-2"><tt>poll</tt>(2)</a>, <a href="../816-5167/read-2.html#REFMAN2read-2"><tt>read</tt>(2)</a>, <a href="../816-5167/write-2.html#REFMAN2write-2"><tt>write</tt>(2)</a>, <a href="../816-5175/attributes-5.html#REFMAN5attributes-5"><tt>attributes</tt>(5)</a>, <a href="audiocs-7d.html#scrolltoc"><tt>audiocs</tt>(7D)</a>, <a href="audioens-7d.html#scrolltoc"><tt>audioens</tt>(7D)</a>, <a href="audiots-7d.html#scrolltoc"><tt>audiots</tt>(7D)</a>, <a href="dbri-7d.html#scrolltoc"><tt>dbri</tt>(7D)</a>, <a href="sbpro-7d.html#scrolltoc"><tt>sbpro</tt>(7D)</a>, <a href="usb-ac-7d.html#scrolltoc"><tt>usb_ac</tt>(7D)</a>, <a href="audio-support-7i.html#scrolltoc"><tt>audio_support</tt>(7I)</a>, <a href="mixer-7i.html#scrolltoc"><tt>mixer</tt>(7I)</a>, <a href="streamio-7i.html#scrolltoc"><tt>streamio</tt>(7I)</a> <h2>Bugs</h2> Due to a <var>feature</var> of the STREAMS implementation, programs that are terminated or exit without closing the <tt>audio</tt> device may hang for a short period while audio output drains. In general, programs that produce audio output should catch the <tt>SIGINT</tt> signal and flush the output stream before exiting.On LX machines running Solaris 2.3, catting a demo audio file to the audio device <tt>/dev/audio</tt> does not work. Use the <tt>audioplay</tt> command on LX machines instead of <tt>cat</tt>. <h3>FUTURE DIRECTIONS</h3> Future audio drivers should use the <a href="mixer-7i.html#scrolltoc"><tt>mixer</tt>(7I)</a> audio device to gain access to new features. </div> <div class="BottomPageControlPane"> <table class="pagecontrol"> <tr> <td> <div class="pagefooterlinks"> Copyright © 1993, 2013, Oracle and/or its affiliates. All rights reserved. <a href="docinfo.html#scrolltoc">Legal Notices</a> </div> </td> <td class="pagenavlinks"> <a href="audio1575-7d.html#scrolltoc"><img src="graphics/leftButton.png" border="0" alt="Previous" title="Previous"></a> <a href="audio810-7d.html#scrolltoc"><img src="graphics/rightButton.png" border="0" alt="Next" title="Next"></a> </td> </tr> </table> </div> </body> </html>