← Back to branch summary

~ubuntu-branches/debian/squeeze/erlang/squeeze

« back to all changes in this revision

Viewing changes to system/doc/reference_manual/ports.xml

  • Committer: Bazaar Package Importer
  • Author(s): Sergei Golovan
  • Date: 2010-03-09 17:34:57 UTC
  • mfrom: (10.1.2 sid)
  • Revision ID: james.westby@ubuntu.com-20100309173457-4yd6hlcb2osfhx31
Tags: 1:13.b.4-dfsg-3
Manpages in section 1 are needed even if only arch-dependent packages are
built. So, re-enabled them.

Show diffs side-by-side

added added

removed removed

Lines of Context:
system/doc/reference_manual/ports.xml
 
1
<?xml version="1.0" encoding="latin1" ?>
 
2
<!DOCTYPE chapter SYSTEM "chapter.dtd">
 
3
 
 
4
<chapter>
 
5
  <header>
 
6
    <copyright>
 
7
      <year>2004</year><year>2009</year>
 
8
      <holder>Ericsson AB. All Rights Reserved.</holder>
 
9
    </copyright>
 
10
    <legalnotice>
 
11
      The contents of this file are subject to the Erlang Public License,
 
12
      Version 1.1, (the "License"); you may not use this file except in
 
13
      compliance with the License. You should have received a copy of the
 
14
      Erlang Public License along with this software. If not, it can be
 
15
      retrieved online at http://www.erlang.org/.
 
16
    
 
17
      Software distributed under the License is distributed on an "AS IS"
 
18
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 
19
      the License for the specific language governing rights and limitations
 
20
      under the License.
 
21
    
 
22
    </legalnotice>
 
23
 
 
24
    <title>Ports and Port Drivers</title>
 
25
    <prepared></prepared>
 
26
    <docno></docno>
 
27
    <date></date>
 
28
    <rev></rev>
 
29
    <file>ports.xml</file>
 
30
  </header>
 
31
  <p>Examples of how to use ports and port drivers can be found in
 
32
    <em>Interoperability Tutorial</em>. The BIFs mentioned are as usual
 
33
    documented in <c>erlang(3)</c>.</p>
 
34
 
 
35
  <section>
 
36
    <title>Ports</title>
 
37
    <p><em>Ports</em> provide the basic mechanism for communication
 
38
      with the external world, from Erlang's point of view. They
 
39
      provide a byte-oriented interface to an external program. When a
 
40
      port has been created, Erlang can communicate with it by sending
 
41
      and receiving lists of bytes, including binaries.</p>
 
42
    <p>The Erlang process which creates a port is said to be
 
43
      the <em>port owner</em>, or the <em>connected process</em> of
 
44
      the port. All communication to and from the port should go via
 
45
      the port owner. If the port owner terminates, so will the port
 
46
      (and the external program, if it is written correctly).</p>
 
47
    <p>The external program resides in another OS process. By default,
 
48
      it should read from standard input (file descriptor 0) and write
 
49
      to standard output (file descriptor 1). The external program
 
50
      should terminate when the port is closed.</p>
 
51
  </section>
 
52
 
 
53
  <section>
 
54
    <title>Port Drivers</title>
 
55
    <p>It is also possible to write a driver in C according to certain
 
56
      principles and dynamically link it to the Erlang runtime system.
 
57
      The linked-in driver looks like a port from the Erlang
 
58
      programmer's point of view and is called a <em>port driver</em>.</p>
 
59
    <warning>
 
60
      <p>An erroneous port driver will cause the entire Erlang runtime
 
61
        system to leak memory, hang or crash.</p>
 
62
    </warning>
 
63
    <p>Port drivers are documented in <c>erl_driver(4)</c>,
 
64
      <c>driver_entry(1)</c> and <c>erl_ddll(3)</c>.</p>
 
65
  </section>
 
66
 
 
67
  <section>
 
68
    <title>Port BIFs</title>
 
69
    <p>To create a port:</p>
 
70
    <table>
 
71
      <row>
 
72
        <cell align="left" valign="middle"><c>open_port(PortName, PortSettings</c></cell>
 
73
        <cell align="left" valign="middle">Returns a port identifier <c>Port</c>as the result of opening a new Erlang port. Messages can be sent to and received from a port identifier, just like a pid. Port identifiers can also be linked to or registered under a name using <c>link/1</c>and <c>register/2</c>.</cell>
 
74
      </row>
 
75
      <tcaption>Port Creation BIF.</tcaption>
 
76
    </table>
 
77
    <p><c>PortName</c> is usually a tuple <c>{spawn,Command}</c>, where
 
78
      the string <c>Command</c> is the name of the external program.
 
79
      The external program runs outside the Erlang workspace unless a
 
80
      port driver with the name <c>Command</c> is found. If found, that
 
81
      driver is started.</p>
 
82
    <p><c>PortSettings</c> is a list of settings (options) for the port.
 
83
      The list typically contains at least a tuple <c>{packet,N}</c>
 
84
      which specifies that data sent between the port and the external
 
85
      program are preceded by an N-byte length indicator. Valid values
 
86
      for N are 1, 2 or 4. If binaries should be used instead of lists
 
87
      of bytes, the option <c>binary</c> must be included.</p>
 
88
    <p>The port owner <c>Pid</c> can communicate with the port
 
89
      <c>Port</c> by sending and receiving messages. (In fact, any
 
90
      process can send the messages to the port, but the messages from
 
91
      the port always go to the port owner).</p>
 
92
    <p>Below, <c>Data</c> must be an I/O list. An I/O list is a binary
 
93
      or a (possibly deep) list of binaries or integers in the range
 
94
      0..255.</p>
 
95
    <table>
 
96
      <row>
 
97
        <cell align="left" valign="middle"><c>{Pid,{command,Data}}</c></cell>
 
98
        <cell align="left" valign="middle">Sends <c>Data</c>to the port.</cell>
 
99
      </row>
 
100
      <row>
 
101
        <cell align="left" valign="middle"><c>{Pid,close}</c></cell>
 
102
        <cell align="left" valign="middle">Closes the port. Unless the port is already closed, the port replies with <c>{Port,closed}</c>when all buffers have been flushed and the port really closes.</cell>
 
103
      </row>
 
104
      <row>
 
105
        <cell align="left" valign="middle"><c>{Pid,{connect,NewPid}}</c></cell>
 
106
        <cell align="left" valign="middle">Sets the port owner of <c>Port</c>to <c>NewPid</c>. Unless the port is already closed, the port replies with<c>{Port,connected}</c>to the old port owner. Note that the old port owner is still linked to the port, but the new port owner is not.</cell>
 
107
      </row>
 
108
      <tcaption>Messages Sent To a Port.</tcaption>
 
109
    </table>
 
110
    <table>
 
111
      <row>
 
112
        <cell align="left" valign="middle"><c>{Port,{data,Data}}</c></cell>
 
113
        <cell align="left" valign="middle"><c>Data</c>is received from the external program.</cell>
 
114
      </row>
 
115
      <row>
 
116
        <cell align="left" valign="middle"><c>{Port,closed}</c></cell>
 
117
        <cell align="left" valign="middle">Reply to <c>Port ! {Pid,close}</c>.</cell>
 
118
      </row>
 
119
      <row>
 
120
        <cell align="left" valign="middle"><c>{Port,connected}</c></cell>
 
121
        <cell align="left" valign="middle">Reply to <c>Port ! {Pid,{connect,NewPid}}</c></cell>
 
122
      </row>
 
123
      <row>
 
124
        <cell align="left" valign="middle"><c>{'EXIT',Port,Reason}</c></cell>
 
125
        <cell align="left" valign="middle">If the port has terminated for some reason.</cell>
 
126
      </row>
 
127
      <tcaption>Messages Received From a Port.</tcaption>
 
128
    </table>
 
129
    <p>Instead of sending and receiving messages, there are also a
 
130
      number of BIFs that can be used. These can be called by any
 
131
      process, not only the port owner.</p>
 
132
    <table>
 
133
      <row>
 
134
        <cell align="left" valign="middle"><c>port_command(Port,Data)</c></cell>
 
135
        <cell align="left" valign="middle">Sends <c>Data</c>to the port.</cell>
 
136
      </row>
 
137
      <row>
 
138
        <cell align="left" valign="middle"><c>port_close(Port)</c></cell>
 
139
        <cell align="left" valign="middle">Closes the port.</cell>
 
140
      </row>
 
141
      <row>
 
142
        <cell align="left" valign="middle"><c>port_connect(Port,NewPid)</c></cell>
 
143
        <cell align="left" valign="middle">Sets the port owner of <c>Port</c>to <c>NewPid</c>. The old port owner <c>Pid</c>stays linked to the port and have to call <c>unlink(Port)</c>if this is not desired.</cell>
 
144
      </row>
 
145
      <row>
 
146
        <cell align="left" valign="middle"><c>erlang:port_info(Port,Item)</c></cell>
 
147
        <cell align="left" valign="middle">Returns information as specified by <c>Item</c>.</cell>
 
148
      </row>
 
149
      <row>
 
150
        <cell align="left" valign="middle"><c>erlang:ports()</c></cell>
 
151
        <cell align="left" valign="middle">Returns a list of all ports on the current node.</cell>
 
152
      </row>
 
153
      <tcaption>Port BIFs.</tcaption>
 
154
    </table>
 
155
    <p>There are some additional BIFs that only apply to port drivers:
 
156
      <c>port_control/3</c> and <c>erlang:port_call/3</c>.</p>
 
157
  </section>
 
158
</chapter>
 
159