1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
5 <title>GUnixFDList</title>
6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7 <link rel="home" href="index.html" title="GIO Reference Manual">
8 <link rel="up" href="networking.html" title="Low-level network support">
9 <link rel="prev" href="GSocketControlMessage.html" title="GSocketControlMessage">
10 <link rel="next" href="GUnixFDMessage.html" title="GUnixFDMessage">
11 <meta name="generator" content="GTK-Doc V1.18 (XML mode)">
12 <link rel="stylesheet" href="style.css" type="text/css">
14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
17 <td><a accesskey="p" href="GSocketControlMessage.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
18 <td><a accesskey="u" href="networking.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
19 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
20 <th width="100%" align="center">GIO Reference Manual</th>
21 <td><a accesskey="n" href="GUnixFDMessage.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
23 <tr><td colspan="5" class="shortcuts">
24 <a href="#GUnixFDList.synopsis" class="shortcut">Top</a>
26 <a href="#GUnixFDList.description" class="shortcut">Description</a>
28 <a href="#GUnixFDList.object-hierarchy" class="shortcut">Object Hierarchy</a>
31 <div class="refentry">
32 <a name="GUnixFDList"></a><div class="titlepage"></div>
33 <div class="refnamediv"><table width="100%"><tr>
35 <h2><span class="refentrytitle"><a name="GUnixFDList.top_of_page"></a>GUnixFDList</span></h2>
36 <p>GUnixFDList — An object containing a set of UNIX file descriptors</p>
38 <td valign="top" align="right"></td>
40 <div class="refsynopsisdiv">
41 <a name="GUnixFDList.synopsis"></a><h2>Synopsis</h2>
42 <pre class="synopsis">
43 #include <gio/gunixfdlist.h>
45 <a class="link" href="GUnixFDList.html#GUnixFDList-struct" title="GUnixFDList">GUnixFDList</a>;
46 <a class="link" href="GUnixFDList.html" title="GUnixFDList"><span class="returnvalue">GUnixFDList</span></a> * <a class="link" href="GUnixFDList.html#g-unix-fd-list-new-from-array" title="g_unix_fd_list_new_from_array ()">g_unix_fd_list_new_from_array</a> (<em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> *fds</code></em>,
47 <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> n_fds</code></em>);
48 <a class="link" href="GUnixFDList.html" title="GUnixFDList"><span class="returnvalue">GUnixFDList</span></a> * <a class="link" href="GUnixFDList.html#g-unix-fd-list-new" title="g_unix_fd_list_new ()">g_unix_fd_list_new</a> (<em class="parameter"><code><span class="type">void</span></code></em>);
49 <a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="returnvalue">gint</span></a> <a class="link" href="GUnixFDList.html#g-unix-fd-list-get-length" title="g_unix_fd_list_get_length ()">g_unix_fd_list_get_length</a> (<em class="parameter"><code><a class="link" href="GUnixFDList.html" title="GUnixFDList"><span class="type">GUnixFDList</span></a> *list</code></em>);
50 <a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="returnvalue">gint</span></a> <a class="link" href="GUnixFDList.html#g-unix-fd-list-get" title="g_unix_fd_list_get ()">g_unix_fd_list_get</a> (<em class="parameter"><code><a class="link" href="GUnixFDList.html" title="GUnixFDList"><span class="type">GUnixFDList</span></a> *list</code></em>,
51 <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> index_</code></em>,
52 <em class="parameter"><code><a href="./../glib/glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);
53 const <a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="returnvalue">gint</span></a> * <a class="link" href="GUnixFDList.html#g-unix-fd-list-peek-fds" title="g_unix_fd_list_peek_fds ()">g_unix_fd_list_peek_fds</a> (<em class="parameter"><code><a class="link" href="GUnixFDList.html" title="GUnixFDList"><span class="type">GUnixFDList</span></a> *list</code></em>,
54 <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> *length</code></em>);
55 <a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="returnvalue">gint</span></a> * <a class="link" href="GUnixFDList.html#g-unix-fd-list-steal-fds" title="g_unix_fd_list_steal_fds ()">g_unix_fd_list_steal_fds</a> (<em class="parameter"><code><a class="link" href="GUnixFDList.html" title="GUnixFDList"><span class="type">GUnixFDList</span></a> *list</code></em>,
56 <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> *length</code></em>);
57 <a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="returnvalue">gint</span></a> <a class="link" href="GUnixFDList.html#g-unix-fd-list-append" title="g_unix_fd_list_append ()">g_unix_fd_list_append</a> (<em class="parameter"><code><a class="link" href="GUnixFDList.html" title="GUnixFDList"><span class="type">GUnixFDList</span></a> *list</code></em>,
58 <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> fd</code></em>,
59 <em class="parameter"><code><a href="./../glib/glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);
62 <div class="refsect1">
63 <a name="GUnixFDList.object-hierarchy"></a><h2>Object Hierarchy</h2>
64 <pre class="synopsis">
65 <a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#GObject">GObject</a>
69 <div class="refsect1">
70 <a name="GUnixFDList.description"></a><h2>Description</h2>
72 A <a class="link" href="GUnixFDList.html" title="GUnixFDList"><span class="type">GUnixFDList</span></a> contains a list of file descriptors. It owns the file
73 descriptors that it contains, closing them when finalized.
76 It may be wrapped in a <a class="link" href="GUnixFDMessage.html" title="GUnixFDMessage"><span class="type">GUnixFDMessage</span></a> and sent over a <a class="link" href="GSocket.html" title="GSocket"><span class="type">GSocket</span></a> in
77 the <code class="literal">G_SOCKET_ADDRESS_UNIX</code> family by using <a class="link" href="GSocket.html#g-socket-send-message" title="g_socket_send_message ()"><code class="function">g_socket_send_message()</code></a>
78 and received using <a class="link" href="GSocket.html#g-socket-receive-message" title="g_socket_receive_message ()"><code class="function">g_socket_receive_message()</code></a>.
81 Note that <code class="filename"><gio/gunixfdlist.h></code> belongs to
82 the UNIX-specific GIO interfaces, thus you have to use the
83 <code class="filename">gio-unix-2.0.pc</code> pkg-config file when using it.
86 <div class="refsect1">
87 <a name="GUnixFDList.details"></a><h2>Details</h2>
88 <div class="refsect2">
89 <a name="GUnixFDList-struct"></a><h3>GUnixFDList</h3>
90 <pre class="programlisting">typedef struct _GUnixFDList GUnixFDList;</pre>
93 <div class="refsect2">
94 <a name="g-unix-fd-list-new-from-array"></a><h3>g_unix_fd_list_new_from_array ()</h3>
95 <pre class="programlisting"><a class="link" href="GUnixFDList.html" title="GUnixFDList"><span class="returnvalue">GUnixFDList</span></a> * g_unix_fd_list_new_from_array (<em class="parameter"><code>const <a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> *fds</code></em>,
96 <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> n_fds</code></em>);</pre>
98 Creates a new <a class="link" href="GUnixFDList.html" title="GUnixFDList"><span class="type">GUnixFDList</span></a> containing the file descriptors given in
99 <em class="parameter"><code>fds</code></em>. The file descriptors become the property of the new list and
100 may no longer be used by the caller. The array itself is owned by
104 Each file descriptor in the array should be set to close-on-exec.
107 If <em class="parameter"><code>n_fds</code></em> is -1 then <em class="parameter"><code>fds</code></em> must be terminated with -1.
109 <div class="variablelist"><table border="0">
110 <col align="left" valign="top">
113 <td><p><span class="term"><em class="parameter"><code>fds</code></em> :</span></p></td>
114 <td>the initial list of file descriptors. <span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=n_fds]</span>
118 <td><p><span class="term"><em class="parameter"><code>n_fds</code></em> :</span></p></td>
119 <td>the length of <span class="type">fds</span>, or -1</td>
122 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
123 <td>a new <a class="link" href="GUnixFDList.html" title="GUnixFDList"><span class="type">GUnixFDList</span></a>
128 <p class="since">Since 2.24</p>
131 <div class="refsect2">
132 <a name="g-unix-fd-list-new"></a><h3>g_unix_fd_list_new ()</h3>
133 <pre class="programlisting"><a class="link" href="GUnixFDList.html" title="GUnixFDList"><span class="returnvalue">GUnixFDList</span></a> * g_unix_fd_list_new (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
135 Creates a new <a class="link" href="GUnixFDList.html" title="GUnixFDList"><span class="type">GUnixFDList</span></a> containing no file descriptors.
137 <div class="variablelist"><table border="0">
138 <col align="left" valign="top">
140 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
141 <td>a new <a class="link" href="GUnixFDList.html" title="GUnixFDList"><span class="type">GUnixFDList</span></a>
145 <p class="since">Since 2.24</p>
148 <div class="refsect2">
149 <a name="g-unix-fd-list-get-length"></a><h3>g_unix_fd_list_get_length ()</h3>
150 <pre class="programlisting"><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="returnvalue">gint</span></a> g_unix_fd_list_get_length (<em class="parameter"><code><a class="link" href="GUnixFDList.html" title="GUnixFDList"><span class="type">GUnixFDList</span></a> *list</code></em>);</pre>
152 Gets the length of <em class="parameter"><code>list</code></em> (ie: the number of file descriptors
155 <div class="variablelist"><table border="0">
156 <col align="left" valign="top">
159 <td><p><span class="term"><em class="parameter"><code>list</code></em> :</span></p></td>
160 <td>a <a class="link" href="GUnixFDList.html" title="GUnixFDList"><span class="type">GUnixFDList</span></a>
164 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
165 <td>the length of <em class="parameter"><code>list</code></em>
170 <p class="since">Since 2.24</p>
173 <div class="refsect2">
174 <a name="g-unix-fd-list-get"></a><h3>g_unix_fd_list_get ()</h3>
175 <pre class="programlisting"><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="returnvalue">gint</span></a> g_unix_fd_list_get (<em class="parameter"><code><a class="link" href="GUnixFDList.html" title="GUnixFDList"><span class="type">GUnixFDList</span></a> *list</code></em>,
176 <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> index_</code></em>,
177 <em class="parameter"><code><a href="./../glib/glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre>
179 Gets a file descriptor out of <em class="parameter"><code>list</code></em>.
182 <em class="parameter"><code>index_</code></em> specifies the index of the file descriptor to get. It is a
183 programmer error for <em class="parameter"><code>index_</code></em> to be out of range; see
184 <a class="link" href="GUnixFDList.html#g-unix-fd-list-get-length" title="g_unix_fd_list_get_length ()"><code class="function">g_unix_fd_list_get_length()</code></a>.
187 The file descriptor is duplicated using <code class="function">dup()</code> and set as
188 close-on-exec before being returned. You must call <code class="function">close()</code> on it
192 A possible cause of failure is exceeding the per-process or
193 system-wide file descriptor limit.
195 <div class="variablelist"><table border="0">
196 <col align="left" valign="top">
199 <td><p><span class="term"><em class="parameter"><code>list</code></em> :</span></p></td>
200 <td>a <a class="link" href="GUnixFDList.html" title="GUnixFDList"><span class="type">GUnixFDList</span></a>
204 <td><p><span class="term"><em class="parameter"><code>index_</code></em> :</span></p></td>
205 <td>the index into the list</td>
208 <td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
209 <td>a <a href="./../glib/glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> pointer</td>
212 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
213 <td>the file descriptor, or -1 in case of error</td>
217 <p class="since">Since 2.24</p>
220 <div class="refsect2">
221 <a name="g-unix-fd-list-peek-fds"></a><h3>g_unix_fd_list_peek_fds ()</h3>
222 <pre class="programlisting">const <a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="returnvalue">gint</span></a> * g_unix_fd_list_peek_fds (<em class="parameter"><code><a class="link" href="GUnixFDList.html" title="GUnixFDList"><span class="type">GUnixFDList</span></a> *list</code></em>,
223 <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> *length</code></em>);</pre>
225 Returns the array of file descriptors that is contained in this
229 After this call, the descriptors remain the property of <em class="parameter"><code>list</code></em>. The
230 caller must not close them and must not free the array. The array is
231 valid only until <em class="parameter"><code>list</code></em> is changed in any way.
234 If <em class="parameter"><code>length</code></em> is non-<a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> then it is set to the number of file
235 descriptors in the returned array. The returned array is also
239 This function never returns <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. In case there are no file
240 descriptors contained in <em class="parameter"><code>list</code></em>, an empty array is returned.
242 <div class="variablelist"><table border="0">
243 <col align="left" valign="top">
246 <td><p><span class="term"><em class="parameter"><code>list</code></em> :</span></p></td>
247 <td>a <a class="link" href="GUnixFDList.html" title="GUnixFDList"><span class="type">GUnixFDList</span></a>
251 <td><p><span class="term"><em class="parameter"><code>length</code></em> :</span></p></td>
252 <td>pointer to the length of the returned
253 array, or <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. <span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
257 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
259 descriptors. <span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=length][<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span>
264 <p class="since">Since 2.24</p>
267 <div class="refsect2">
268 <a name="g-unix-fd-list-steal-fds"></a><h3>g_unix_fd_list_steal_fds ()</h3>
269 <pre class="programlisting"><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="returnvalue">gint</span></a> * g_unix_fd_list_steal_fds (<em class="parameter"><code><a class="link" href="GUnixFDList.html" title="GUnixFDList"><span class="type">GUnixFDList</span></a> *list</code></em>,
270 <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> *length</code></em>);</pre>
272 Returns the array of file descriptors that is contained in this
276 After this call, the descriptors are no longer contained in
277 <em class="parameter"><code>list</code></em>. Further calls will return an empty list (unless more
278 descriptors have been added).
281 The return result of this function must be freed with <a href="./../glib/glib/glib-Memory-Allocation.html#g-free"><code class="function">g_free()</code></a>.
282 The caller is also responsible for closing all of the file
283 descriptors. The file descriptors in the array are set to
287 If <em class="parameter"><code>length</code></em> is non-<a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> then it is set to the number of file
288 descriptors in the returned array. The returned array is also
292 This function never returns <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. In case there are no file
293 descriptors contained in <em class="parameter"><code>list</code></em>, an empty array is returned.
295 <div class="variablelist"><table border="0">
296 <col align="left" valign="top">
299 <td><p><span class="term"><em class="parameter"><code>list</code></em> :</span></p></td>
300 <td>a <a class="link" href="GUnixFDList.html" title="GUnixFDList"><span class="type">GUnixFDList</span></a>
304 <td><p><span class="term"><em class="parameter"><code>length</code></em> :</span></p></td>
305 <td>pointer to the length of the returned
306 array, or <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. <span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
310 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
312 descriptors. <span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=length][<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
317 <p class="since">Since 2.24</p>
320 <div class="refsect2">
321 <a name="g-unix-fd-list-append"></a><h3>g_unix_fd_list_append ()</h3>
322 <pre class="programlisting"><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="returnvalue">gint</span></a> g_unix_fd_list_append (<em class="parameter"><code><a class="link" href="GUnixFDList.html" title="GUnixFDList"><span class="type">GUnixFDList</span></a> *list</code></em>,
323 <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> fd</code></em>,
324 <em class="parameter"><code><a href="./../glib/glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre>
326 Adds a file descriptor to <em class="parameter"><code>list</code></em>.
329 The file descriptor is duplicated using <code class="function">dup()</code>. You keep your copy
330 of the descriptor and the copy contained in <em class="parameter"><code>list</code></em> will be closed
331 when <em class="parameter"><code>list</code></em> is finalized.
334 A possible cause of failure is exceeding the per-process or
335 system-wide file descriptor limit.
338 The index of the file descriptor in the list is returned. If you use
339 this index with <a class="link" href="GUnixFDList.html#g-unix-fd-list-get" title="g_unix_fd_list_get ()"><code class="function">g_unix_fd_list_get()</code></a> then you will receive back a
340 duplicated copy of the same file descriptor.
342 <div class="variablelist"><table border="0">
343 <col align="left" valign="top">
346 <td><p><span class="term"><em class="parameter"><code>list</code></em> :</span></p></td>
347 <td>a <a class="link" href="GUnixFDList.html" title="GUnixFDList"><span class="type">GUnixFDList</span></a>
351 <td><p><span class="term"><em class="parameter"><code>fd</code></em> :</span></p></td>
352 <td>a valid open file descriptor</td>
355 <td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
356 <td>a <a href="./../glib/glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> pointer</td>
359 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
360 <td>the index of the appended fd in case of success, else -1
361 (and <em class="parameter"><code>error</code></em> is set)</td>
365 <p class="since">Since 2.24</p>
368 <div class="refsect1">
369 <a name="GUnixFDList.see-also"></a><h2>See Also</h2>
370 <a class="link" href="GUnixFDMessage.html" title="GUnixFDMessage"><span class="type">GUnixFDMessage</span></a>
375 Generated by GTK-Doc V1.18</div>