~ubuntu-branches/debian/jessie/glib2.0/jessie

use <link linkend="g-io-add-watch"><function>g_io_add_watch()</function></link> or <link linkend="g-io-add-watch-full"><function>g_io_add_watch_full()</function></link>. Here you specify which events

177

174

you are interested in on the <link linkend="GIOChannel"><type>GIOChannel</type></link>, and provide a function to be

196

193

</para>

197

194

</refsect1>

198

195

199

196

200

197

<title role="details.title">Details</title>

201

202

<title><anchor id="GIOChannel" role="struct"/>GIOChannel</title>

203

<indexterm><primary>GIOChannel</primary></indexterm><programlisting>typedef struct {

198

199

<title>GIOChannel</title>

200

<indexterm zone="GIOChannel"><primary sortas="GIOChannel">GIOChannel</primary></indexterm><programlisting>typedef struct {

204

201

} GIOChannel;

205

202

</programlisting>

206

203

<para>

207

204

A data structure representing an IO Channel. The fields should be considered

208

205

private and should only be accessed with the following functions.

209

206

</para></refsect2>

210

211

<title><anchor id="g-io-channel-unix-new" role="function"/>g_io_channel_unix_new ()</title>

212

<indexterm><primary>g_io_channel_unix_new</primary></indexterm><programlisting><link linkend="GIOChannel">GIOChannel</link>* g_io_channel_unix_new (<link linkend="int">int</link> fd);</programlisting>

207

208

<title>g_io_channel_unix_new ()</title>

209

<indexterm zone="g-io-channel-unix-new"><primary sortas="g_io_channel_unix_new">g_io_channel_unix_new</primary></indexterm><programlisting><link linkend="GIOChannel">GIOChannel</link>* g_io_channel_unix_new (<link linkend="int">int</link> fd);</programlisting>

213

210

<para>

214

211

Creates a new <link linkend="GIOChannel"><type>GIOChannel</type></link> given a file descriptor.

215

212

On UNIX systems this works for plain files, pipes, and sockets.

225

222

</para>

226

223

<para>

227

224

If you want to read raw binary data without interpretation, then

228

call the <link linkend="g-io-channel-set-encoding"><function>g_io_channel_set_encoding()</function></link> function with <link linkend="NULL:CAPS"><literal>NULL</literal></link> for the

225

call the <link linkend="g-io-channel-set-encoding"><function>g_io_channel_set_encoding()</function></link> function with <link linkend="NULL--CAPS"><literal>NULL</literal></link> for the

229

226

encoding argument.

230

227

</para>

231

228

<para>

236

233

descriptor and socket. If that happens a warning is issued, and GLib

237

234

assumes that it is the file descriptor you mean.

238

235

</para><variablelist role="params">

239

236

240

237

<listitem><simpara>a file descriptor.

241

238

</simpara></listitem></varlistentry>

242

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a new <link linkend="GIOChannel"><type>GIOChannel</type></link>.

243

244

239

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a new <link linkend="GIOChannel"><type>GIOChannel</type></link>.

245

240

</simpara></listitem></varlistentry>

246

241

</variablelist></refsect2>

247

248

<title><anchor id="g-io-channel-unix-get-fd" role="function"/>g_io_channel_unix_get_fd ()</title>

249

<indexterm><primary>g_io_channel_unix_get_fd</primary></indexterm><programlisting><link linkend="gint">gint</link> g_io_channel_unix_get_fd (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>

242

243

<title>g_io_channel_unix_get_fd ()</title>

244

<indexterm zone="g-io-channel-unix-get-fd"><primary sortas="g_io_channel_unix_get_fd">g_io_channel_unix_get_fd</primary></indexterm><programlisting><link linkend="gint">gint</link> g_io_channel_unix_get_fd (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>

250

245

<para>

251

246

Returns the file descriptor of the <link linkend="GIOChannel"><type>GIOChannel</type></link>.

252

247

</para>

253

248

<para>

254

249

On Windows this function returns the file descriptor or socket of the <link linkend="GIOChannel"><type>GIOChannel</type></link>.

255

250

</para><variablelist role="params">

256

<varlistentry><term><parameter>channel</parameter> :</term>

251

<varlistentry><term><parameter>channel</parameter> :</term>

257

252

<listitem><simpara>a <link linkend="GIOChannel"><type>GIOChannel</type></link>, created with <link linkend="g-io-channel-unix-new"><function>g_io_channel_unix_new()</function></link>.

258

253

</simpara></listitem></varlistentry>

259

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the file descriptor of the <link linkend="GIOChannel"><type>GIOChannel</type></link>.

260

261

254

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the file descriptor of the <link linkend="GIOChannel"><type>GIOChannel</type></link>.

262

255

</simpara></listitem></varlistentry>

263

256

</variablelist></refsect2>

264

265

<title><anchor id="g-io-channel-win32-new-fd" role="function"/>g_io_channel_win32_new_fd ()</title>

266

<indexterm><primary>g_io_channel_win32_new_fd</primary></indexterm><programlisting><link linkend="GIOChannel">GIOChannel</link>* g_io_channel_win32_new_fd (<link linkend="gint">gint</link> fd);</programlisting>

257

258

<title>g_io_channel_win32_new_fd ()</title>

259

<indexterm zone="g-io-channel-win32-new-fd"><primary sortas="g_io_channel_win32_new_fd">g_io_channel_win32_new_fd</primary></indexterm><programlisting><link linkend="GIOChannel">GIOChannel</link>* g_io_channel_win32_new_fd (<link linkend="gint">gint</link> fd);</programlisting>

267

260

<para>

268

Creates a new <link linkend="GIOChannel"><type>GIOChannel</type></link> given a file descriptor on Windows.

261

Creates a new <link linkend="GIOChannel"><type>GIOChannel</type></link> given a file descriptor on Windows.

269

262

This works for file descriptors from the C runtime.

270

263

</para>

271

264

<para>

291

284

<para>

292

285

This function is available only in GLib on Windows.

293

286

</para><variablelist role="params">

294

287

295

288

<listitem><simpara>a C library file descriptor.

296

289

</simpara></listitem></varlistentry>

297

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a new <link linkend="GIOChannel"><type>GIOChannel</type></link>.

298

299

290

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a new <link linkend="GIOChannel"><type>GIOChannel</type></link>.

300

291

</simpara></listitem></varlistentry>

301

292

</variablelist></refsect2>

302

303

<title><anchor id="g-io-channel-win32-new-socket" role="function"/>g_io_channel_win32_new_socket ()</title>

304

<indexterm><primary>g_io_channel_win32_new_socket</primary></indexterm><programlisting><link linkend="GIOChannel">GIOChannel</link>* g_io_channel_win32_new_socket (<link linkend="gint">gint</link> socket);</programlisting>

293

294

<title>g_io_channel_win32_new_socket ()</title>

295

<indexterm zone="g-io-channel-win32-new-socket"><primary sortas="g_io_channel_win32_new_socket">g_io_channel_win32_new_socket</primary></indexterm><programlisting><link linkend="GIOChannel">GIOChannel</link> * g_io_channel_win32_new_socket (<link linkend="gint">gint</link> socket);</programlisting>

305

296

<para>

306

297

Creates a new <link linkend="GIOChannel"><type>GIOChannel</type></link> given a socket on Windows.

307

298

</para>

308

299

<para>

309

This function works for sockets created by Winsock.

300

This function works for sockets created by Winsock.

310

301

It's available only in GLib on Windows.

311

302

</para>

312

303

<para>

313

Polling a <link linkend="GSource"><type>GSource</type></link> created to watch a channel for a socket

314

puts the socket in non-blocking mode. This is a side-effect

304

Polling a <link linkend="GSource"><type>GSource</type></link> created to watch a channel for a socket

305

puts the socket in non-blocking mode. This is a side-effect

315

306

of the implementation and unavoidable.

316

307

</para><variablelist role="params">

317

<varlistentry><term><parameter>socket</parameter> :</term>

308

<varlistentry><term><parameter>socket</parameter> :</term>

318

309

<listitem><simpara>a Winsock socket

319

310

</simpara></listitem></varlistentry>

320

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a new <link linkend="GIOChannel"><type>GIOChannel</type></link>

321

322

311

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a new <link linkend="GIOChannel"><type>GIOChannel</type></link>

323

312

</simpara></listitem></varlistentry>

324

313

</variablelist></refsect2>

325

326

<title><anchor id="g-io-channel-win32-new-messages" role="function"/>g_io_channel_win32_new_messages ()</title>

327

<indexterm><primary>g_io_channel_win32_new_messages</primary></indexterm><programlisting><link linkend="GIOChannel">GIOChannel</link>* g_io_channel_win32_new_messages (<link linkend="guint">guint</link> hwnd);</programlisting>

314

315

<title>g_io_channel_win32_new_messages ()</title>

316

<indexterm zone="g-io-channel-win32-new-messages"><primary sortas="g_io_channel_win32_new_messages">g_io_channel_win32_new_messages</primary></indexterm><programlisting><link linkend="GIOChannel">GIOChannel</link> * g_io_channel_win32_new_messages (<link linkend="gsize">gsize</link> hwnd);</programlisting>

328

317

<para>

329

318

Creates a new <link linkend="GIOChannel"><type>GIOChannel</type></link> given a window handle on Windows.

330

319

</para>

332

321

This function creates a <link linkend="GIOChannel"><type>GIOChannel</type></link> that can be used to poll for

333

322

Windows messages for the window in question.

334

323

</para><variablelist role="params">

335

324

336

325

<listitem><simpara>a window handle.

337

326

</simpara></listitem></varlistentry>

338

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a new <link linkend="GIOChannel"><type>GIOChannel</type></link>.

339

340

327

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a new <link linkend="GIOChannel"><type>GIOChannel</type></link>.

341

328

</simpara></listitem></varlistentry>

342

329

</variablelist></refsect2>

343

344

<title><anchor id="g-io-channel-init" role="function"/>g_io_channel_init ()</title>

345

<indexterm><primary>g_io_channel_init</primary></indexterm><programlisting><link linkend="void">void</link> g_io_channel_init (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>

330

331

<title>g_io_channel_init ()</title>

332

<indexterm zone="g-io-channel-init"><primary sortas="g_io_channel_init">g_io_channel_init</primary></indexterm><programlisting><link linkend="void">void</link> g_io_channel_init (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>

346

333

<para>

347

Initializes a <link linkend="GIOChannel"><type>GIOChannel</type></link> struct. This is called by each of the

348

above functions when creating a <link linkend="GIOChannel"><type>GIOChannel</type></link>, and so is not often

349

needed by the application programmer (unless you are creating a

334

Initializes a <link linkend="GIOChannel"><type>GIOChannel</type></link> struct. This is called by each of the

335

above functions when creating a <link linkend="GIOChannel"><type>GIOChannel</type></link>, and so is not often

336

needed by the application programmer (unless you are creating a

350

337

new type of <link linkend="GIOChannel"><type>GIOChannel</type></link>).

351

338

</para><variablelist role="params">

352

<varlistentry><term><parameter>channel</parameter> :</term>

339

<varlistentry><term><parameter>channel</parameter> :</term>

353

340

<listitem><simpara>a <link linkend="GIOChannel"><type>GIOChannel</type></link>

354

355

356

341

</simpara></listitem></varlistentry>

357

342

</variablelist></refsect2>

358

359

<title><anchor id="g-io-channel-new-file" role="function"/>g_io_channel_new_file ()</title>

360

<indexterm><primary>g_io_channel_new_file</primary></indexterm><programlisting><link linkend="GIOChannel">GIOChannel</link>* g_io_channel_new_file (const <link linkend="gchar">gchar</link> *filename,

343

344

<title>g_io_channel_new_file ()</title>

345

<indexterm zone="g-io-channel-new-file"><primary sortas="g_io_channel_new_file">g_io_channel_new_file</primary></indexterm><programlisting><link linkend="GIOChannel">GIOChannel</link>* g_io_channel_new_file (const <link linkend="gchar">gchar</link> *filename,

361

346

const <link linkend="gchar">gchar</link> *mode,

362

347

363

348

<para>

368

353

access the channel after it is closed).</para>

369

354

<para>

370

355

</para><variablelist role="params">

371

<varlistentry><term><parameter>filename</parameter> :</term>

356

<varlistentry><term><parameter>filename</parameter> :</term>

372

357

<listitem><simpara> A string containing the name of a file

373

358

</simpara></listitem></varlistentry>

374

359

375

360

<listitem><simpara> One of "r", "w", "a", "r+", "w+", "a+". These have

376

361

the same meaning as in <link linkend="fopen"><function>fopen()</function></link>

377

362

</simpara></listitem></varlistentry>

378

<varlistentry><term><parameter>error</parameter> :</term>

379

<listitem><simpara> A location to return an error of type <link linkend="G-FILE-ERROR:CAPS"><literal>G_FILE_ERROR</literal></link>

363

<varlistentry><term><parameter>error</parameter> :</term>

364

<listitem><simpara> A location to return an error of type <link linkend="G-FILE-ERROR--CAPS"><literal>G_FILE_ERROR</literal></link>

380

365

</simpara></listitem></varlistentry>

381

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A <link linkend="GIOChannel"><type>GIOChannel</type></link> on success, <link linkend="NULL:CAPS"><literal>NULL</literal></link> on failure.

366

382

367

</simpara></listitem></varlistentry>

383

368

</variablelist></refsect2>

384

385

<title><anchor id="g-io-channel-read-chars" role="function"/>g_io_channel_read_chars ()</title>

386

<indexterm><primary>g_io_channel_read_chars</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_read_chars (<link linkend="GIOChannel">GIOChannel</link> *channel,

369

370

<title>g_io_channel_read_chars ()</title>

371

<indexterm zone="g-io-channel-read-chars"><primary sortas="g_io_channel_read_chars">g_io_channel_read_chars</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_read_chars (<link linkend="GIOChannel">GIOChannel</link> *channel,

387

372

388

373

389

374

391

376

<para>

392

377

Replacement for <link linkend="g-io-channel-read"><function>g_io_channel_read()</function></link> with the new API.</para>

393

378

<para>

394

395

379

</para><variablelist role="params">

396

<varlistentry><term><parameter>channel</parameter> :</term>

380

<varlistentry><term><parameter>channel</parameter> :</term>

397

381

<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>

398

382

</simpara></listitem></varlistentry>

399

383

400

384

<listitem><simpara> a buffer to read data into

401

385

</simpara></listitem></varlistentry>

402

<varlistentry><term><parameter>count</parameter> :</term>

386

<varlistentry><term><parameter>count</parameter> :</term>

403

387

<listitem><simpara> the size of the buffer. Note that the buffer may

404

388

not be complelely filled even if there is data

405

389

in the buffer if the remaining data is not a

406

390

complete character.

407

391

</simpara></listitem></varlistentry>

408

<varlistentry><term><parameter>bytes_read</parameter> :</term>

392

<varlistentry><term><parameter>bytes_read</parameter> :</term>

409

393

<listitem><simpara> The number of bytes read. This may be zero even on

410

success if count < 6 and the channel's encoding is non-<link linkend="NULL:CAPS"><literal>NULL</literal></link>.

394

success if count < 6 and the channel's encoding is non-<link linkend="NULL--CAPS"><literal>NULL</literal></link>.

411

395

This indicates that the next UTF-8 character is too wide for

412

396

the buffer.

413

397

</simpara></listitem></varlistentry>

414

<varlistentry><term><parameter>error</parameter> :</term>

398

<varlistentry><term><parameter>error</parameter> :</term>

415

399

<listitem><simpara> a location to return an error of type <link linkend="GConvertError"><type>GConvertError</type></link>

416

400

or <link linkend="GIOChannelError"><type>GIOChannelError</type></link>.

417

401

</simpara></listitem></varlistentry>

418

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation.

402

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation.

419

403

</simpara></listitem></varlistentry>

420

404

</variablelist></refsect2>

421

422

<title><anchor id="g-io-channel-read-unichar" role="function"/>g_io_channel_read_unichar ()</title>

423

<indexterm><primary>g_io_channel_read_unichar</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_read_unichar (<link linkend="GIOChannel">GIOChannel</link> *channel,

405

406

<title>g_io_channel_read_unichar ()</title>

407

<indexterm zone="g-io-channel-read-unichar"><primary sortas="g_io_channel_read_unichar">g_io_channel_read_unichar</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_read_unichar (<link linkend="GIOChannel">GIOChannel</link> *channel,

424

408

425

409

426

410

<para>

427

411

Reads a Unicode character from <parameter>channel</parameter>.

428

This function cannot be called on a channel with <link linkend="NULL:CAPS"><literal>NULL</literal></link> encoding.</para>

412

This function cannot be called on a channel with <link linkend="NULL--CAPS"><literal>NULL</literal></link> encoding.</para>

429

413

<para>

430

431

414

</para><variablelist role="params">

432

<varlistentry><term><parameter>channel</parameter> :</term>

415

<varlistentry><term><parameter>channel</parameter> :</term>

433

416

<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>

434

417

</simpara></listitem></varlistentry>

435

<varlistentry><term><parameter>thechar</parameter> :</term>

418

<varlistentry><term><parameter>thechar</parameter> :</term>

436

419

<listitem><simpara> a location to return a character

437

420

</simpara></listitem></varlistentry>

438

<varlistentry><term><parameter>error</parameter> :</term>

421

<varlistentry><term><parameter>error</parameter> :</term>

439

422

<listitem><simpara> a location to return an error of type <link linkend="GConvertError"><type>GConvertError</type></link>

440

423

or <link linkend="GIOChannelError"><type>GIOChannelError</type></link>

441

424

</simpara></listitem></varlistentry>

442

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a <link linkend="GIOStatus"><type>GIOStatus</type></link>

425

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a <link linkend="GIOStatus"><type>GIOStatus</type></link>

443

426

</simpara></listitem></varlistentry>

444

427

</variablelist></refsect2>

445

446

<title><anchor id="g-io-channel-read-line" role="function"/>g_io_channel_read_line ()</title>

447

<indexterm><primary>g_io_channel_read_line</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_read_line (<link linkend="GIOChannel">GIOChannel</link> *channel,

428

429

<title>g_io_channel_read_line ()</title>

430

<indexterm zone="g-io-channel-read-line"><primary sortas="g_io_channel_read_line">g_io_channel_read_line</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_read_line (<link linkend="GIOChannel">GIOChannel</link> *channel,

448

431

449

432

450

433

453

436

Reads a line, including the terminating character(s),

454

437

from a <link linkend="GIOChannel"><type>GIOChannel</type></link> into a newly-allocated string.

455

438

<parameter>str_return</parameter> will contain allocated memory if the return

456

is <link linkend="G-IO-STATUS-NORMAL:CAPS"><literal>G_IO_STATUS_NORMAL</literal></link>.</para>

439

is <link linkend="G-IO-STATUS-NORMAL--CAPS"><literal>G_IO_STATUS_NORMAL</literal></link>.</para>

457

440

<para>

458

459

441

</para><variablelist role="params">

460

<varlistentry><term><parameter>channel</parameter> :</term>

442

<varlistentry><term><parameter>channel</parameter> :</term>

461

443

<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>

462

444

</simpara></listitem></varlistentry>

463

<varlistentry><term><parameter>str_return</parameter> :</term>

445

<varlistentry><term><parameter>str_return</parameter> :</term>

464

446

<listitem><simpara> The line read from the <link linkend="GIOChannel"><type>GIOChannel</type></link>, including the

465

447

line terminator. This data should be freed with <link linkend="g-free"><function>g_free()</function></link>

466

448

when no longer needed. This is a nul-terminated string.

467

If a <parameter>length</parameter> of zero is returned, this will be <link linkend="NULL:CAPS"><literal>NULL</literal></link> instead.

468

</simpara></listitem></varlistentry>

469

<varlistentry><term><parameter>length</parameter> :</term>

470

<listitem><simpara> location to store length of the read data, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>

471

</simpara></listitem></varlistentry>

472

<varlistentry><term><parameter>terminator_pos</parameter> :</term>

473

<listitem><simpara> location to store position of line terminator, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>

474

</simpara></listitem></varlistentry>

475

<varlistentry><term><parameter>error</parameter> :</term>

449

If a <parameter>length</parameter> of zero is returned, this will be <link linkend="NULL--CAPS"><literal>NULL</literal></link> instead.

450

</simpara></listitem></varlistentry>

451

<varlistentry><term><parameter>length</parameter> :</term>

452

<listitem><simpara> location to store length of the read data, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>

453

</simpara></listitem></varlistentry>

454

<varlistentry><term><parameter>terminator_pos</parameter> :</term>

455

<listitem><simpara> location to store position of line terminator, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>

456

</simpara></listitem></varlistentry>

457

<varlistentry><term><parameter>error</parameter> :</term>

476

458

<listitem><simpara> A location to return an error of type <link linkend="GConvertError"><type>GConvertError</type></link>

477

459

or <link linkend="GIOChannelError"><type>GIOChannelError</type></link>

478

460

</simpara></listitem></varlistentry>

479

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation.

461

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation.

480

462

</simpara></listitem></varlistentry>

481

463

</variablelist></refsect2>

482

483

<title><anchor id="g-io-channel-read-line-string" role="function"/>g_io_channel_read_line_string ()</title>

484

<indexterm><primary>g_io_channel_read_line_string</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_read_line_string (<link linkend="GIOChannel">GIOChannel</link> *channel,

464

465

<title>g_io_channel_read_line_string ()</title>

466

<indexterm zone="g-io-channel-read-line-string"><primary sortas="g_io_channel_read_line_string">g_io_channel_read_line_string</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_read_line_string (<link linkend="GIOChannel">GIOChannel</link> *channel,

485

467

486

468

487

469

488

470

<para>

489

471

Reads a line from a <link linkend="GIOChannel"><type>GIOChannel</type></link>, using a <link linkend="GString"><type>GString</type></link> as a buffer.</para>

490

472

<para>

491

492

473

</para><variablelist role="params">

493

<varlistentry><term><parameter>channel</parameter> :</term>

474

<varlistentry><term><parameter>channel</parameter> :</term>

494

475

<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>

495

476

</simpara></listitem></varlistentry>

496

<varlistentry><term><parameter>buffer</parameter> :</term>

477

<varlistentry><term><parameter>buffer</parameter> :</term>

497

478

<listitem><simpara> a <link linkend="GString"><type>GString</type></link> into which the line will be written.

498

479

If <parameter>buffer</parameter> already contains data, the old data will

499

480

be overwritten.

500

481

</simpara></listitem></varlistentry>

501

<varlistentry><term><parameter>terminator_pos</parameter> :</term>

502

<listitem><simpara> location to store position of line terminator, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>

482

<varlistentry><term><parameter>terminator_pos</parameter> :</term>

483

<listitem><simpara> location to store position of line terminator, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>

503

484

</simpara></listitem></varlistentry>

504

<varlistentry><term><parameter>error</parameter> :</term>

485

<varlistentry><term><parameter>error</parameter> :</term>

505

486

<listitem><simpara> a location to store an error of type <link linkend="GConvertError"><type>GConvertError</type></link>

506

487

or <link linkend="GIOChannelError"><type>GIOChannelError</type></link>

507

488

</simpara></listitem></varlistentry>

508

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation.

489

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation.

509

490

</simpara></listitem></varlistentry>

510

491

</variablelist></refsect2>

511

512

<title><anchor id="g-io-channel-read-to-end" role="function"/>g_io_channel_read_to_end ()</title>

513

<indexterm><primary>g_io_channel_read_to_end</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_read_to_end (<link linkend="GIOChannel">GIOChannel</link> *channel,

492

493

<title>g_io_channel_read_to_end ()</title>

494

<indexterm zone="g-io-channel-read-to-end"><primary sortas="g_io_channel_read_to_end">g_io_channel_read_to_end</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_read_to_end (<link linkend="GIOChannel">GIOChannel</link> *channel,

514

495

515

496

516

497

517

498

<para>

518

499

Reads all the remaining data from the file.</para>

519

500

<para>

520

521

501

</para><variablelist role="params">

522

<varlistentry><term><parameter>channel</parameter> :</term>

502

<varlistentry><term><parameter>channel</parameter> :</term>

523

503

<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>

524

504

</simpara></listitem></varlistentry>

525

<varlistentry><term><parameter>str_return</parameter> :</term>

505

<varlistentry><term><parameter>str_return</parameter> :</term>

526

506

<listitem><simpara> Location to store a pointer to a string holding

527

507

the remaining data in the <link linkend="GIOChannel"><type>GIOChannel</type></link>. This data should

528

508

be freed with <link linkend="g-free"><function>g_free()</function></link> when no longer needed. This

529

509

data is terminated by an extra nul character, but there

530

510

may be other nuls in the intervening data.

531

511

</simpara></listitem></varlistentry>

532

<varlistentry><term><parameter>length</parameter> :</term>

512

<varlistentry><term><parameter>length</parameter> :</term>

533

513

<listitem><simpara> location to store length of the data

534

514

</simpara></listitem></varlistentry>

535

<varlistentry><term><parameter>error</parameter> :</term>

515

<varlistentry><term><parameter>error</parameter> :</term>

536

516

<listitem><simpara> location to return an error of type <link linkend="GConvertError"><type>GConvertError</type></link>

537

517

or <link linkend="GIOChannelError"><type>GIOChannelError</type></link>

538

518

</simpara></listitem></varlistentry>

539

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="G-IO-STATUS-NORMAL:CAPS"><literal>G_IO_STATUS_NORMAL</literal></link> on success.

540

This function never returns <link linkend="G-IO-STATUS-EOF:CAPS"><literal>G_IO_STATUS_EOF</literal></link>.

519

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="G-IO-STATUS-NORMAL--CAPS"><literal>G_IO_STATUS_NORMAL</literal></link> on success.

520

This function never returns <link linkend="G-IO-STATUS-EOF--CAPS"><literal>G_IO_STATUS_EOF</literal></link>.

541

521

</simpara></listitem></varlistentry>

542

522

</variablelist></refsect2>

543

544

<title><anchor id="g-io-channel-write-chars" role="function"/>g_io_channel_write_chars ()</title>

545

<indexterm><primary>g_io_channel_write_chars</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_write_chars (<link linkend="GIOChannel">GIOChannel</link> *channel,

523

524

<title>g_io_channel_write_chars ()</title>

525

<indexterm zone="g-io-channel-write-chars"><primary sortas="g_io_channel_write_chars">g_io_channel_write_chars</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_write_chars (<link linkend="GIOChannel">GIOChannel</link> *channel,

546

526

const <link linkend="gchar">gchar</link> *buf,

547

527

548

528

551

531

Replacement for <link linkend="g-io-channel-write"><function>g_io_channel_write()</function></link> with the new API.

552

532

</para>

553

533

<para>

554

On seekable channels with encodings other than <link linkend="NULL:CAPS"><literal>NULL</literal></link> or UTF-8, generic

534

On seekable channels with encodings other than <link linkend="NULL--CAPS"><literal>NULL</literal></link> or UTF-8, generic

555

535

mixing of reading and writing is not allowed. A call to <link linkend="g-io-channel-write-chars"><function>g_io_channel_write_chars()</function></link>

556

536

may only be made on a channel from which data has been read in the

557

537

cases described in the documentation for <link linkend="g-io-channel-set-encoding"><function>g_io_channel_set_encoding()</function></link>.</para>

558

538

<para>

559

560

539

</para><variablelist role="params">

561

<varlistentry><term><parameter>channel</parameter> :</term>

540

<varlistentry><term><parameter>channel</parameter> :</term>

562

541

<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>

563

542

</simpara></listitem></varlistentry>

564

543

565

544

<listitem><simpara> a buffer to write data from

566

545

</simpara></listitem></varlistentry>

567

<varlistentry><term><parameter>count</parameter> :</term>

546

<varlistentry><term><parameter>count</parameter> :</term>

568

547

<listitem><simpara> the size of the buffer. If -1, the buffer

569

548

is taken to be a nul-terminated string.

570

549

</simpara></listitem></varlistentry>

571

<varlistentry><term><parameter>bytes_written</parameter> :</term>

550

<varlistentry><term><parameter>bytes_written</parameter> :</term>

572

551

<listitem><simpara> The number of bytes written. This can be nonzero

573

even if the return value is not <link linkend="G-IO-STATUS-NORMAL:CAPS"><literal>G_IO_STATUS_NORMAL</literal></link>.

574

If the return value is <link linkend="G-IO-STATUS-NORMAL:CAPS"><literal>G_IO_STATUS_NORMAL</literal></link> and the

552

even if the return value is not <link linkend="G-IO-STATUS-NORMAL--CAPS"><literal>G_IO_STATUS_NORMAL</literal></link>.

553

If the return value is <link linkend="G-IO-STATUS-NORMAL--CAPS"><literal>G_IO_STATUS_NORMAL</literal></link> and the

575

554

channel is blocking, this will always be equal

576

555

to <parameter>count</parameter> if <parameter>count</parameter> >= 0.

577

556

</simpara></listitem></varlistentry>

578

<varlistentry><term><parameter>error</parameter> :</term>

557

<varlistentry><term><parameter>error</parameter> :</term>

579

558

<listitem><simpara> a location to return an error of type <link linkend="GConvertError"><type>GConvertError</type></link>

580

559

or <link linkend="GIOChannelError"><type>GIOChannelError</type></link>

581

560

</simpara></listitem></varlistentry>

582

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation.

561

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation.

583

562

</simpara></listitem></varlistentry>

584

563

</variablelist></refsect2>

585

586

<title><anchor id="g-io-channel-write-unichar" role="function"/>g_io_channel_write_unichar ()</title>

587

<indexterm><primary>g_io_channel_write_unichar</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_write_unichar (<link linkend="GIOChannel">GIOChannel</link> *channel,

564

565

<title>g_io_channel_write_unichar ()</title>

566

<indexterm zone="g-io-channel-write-unichar"><primary sortas="g_io_channel_write_unichar">g_io_channel_write_unichar</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_write_unichar (<link linkend="GIOChannel">GIOChannel</link> *channel,

588

567

589

568

590

569

<para>

591

570

Writes a Unicode character to <parameter>channel</parameter>.

592

This function cannot be called on a channel with <link linkend="NULL:CAPS"><literal>NULL</literal></link> encoding.</para>

571

This function cannot be called on a channel with <link linkend="NULL--CAPS"><literal>NULL</literal></link> encoding.</para>

593

572

<para>

594

595

573

</para><variablelist role="params">

596

<varlistentry><term><parameter>channel</parameter> :</term>

574

<varlistentry><term><parameter>channel</parameter> :</term>

597

575

<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>

598

576

</simpara></listitem></varlistentry>

599

<varlistentry><term><parameter>thechar</parameter> :</term>

577

<varlistentry><term><parameter>thechar</parameter> :</term>

600

578

<listitem><simpara> a character

601

579

</simpara></listitem></varlistentry>

602

<varlistentry><term><parameter>error</parameter> :</term>

580

<varlistentry><term><parameter>error</parameter> :</term>

603

581

<listitem><simpara> location to return an error of type <link linkend="GConvertError"><type>GConvertError</type></link>

604

582

or <link linkend="GIOChannelError"><type>GIOChannelError</type></link>

605

583

</simpara></listitem></varlistentry>

606

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a <link linkend="GIOStatus"><type>GIOStatus</type></link>

584

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a <link linkend="GIOStatus"><type>GIOStatus</type></link>

607

585

</simpara></listitem></varlistentry>

608

586

</variablelist></refsect2>

609

610

<title><anchor id="g-io-channel-flush" role="function"/>g_io_channel_flush ()</title>

611

<indexterm><primary>g_io_channel_flush</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_flush (<link linkend="GIOChannel">GIOChannel</link> *channel,

587

588

<title>g_io_channel_flush ()</title>

589

<indexterm zone="g-io-channel-flush"><primary sortas="g_io_channel_flush">g_io_channel_flush</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_flush (<link linkend="GIOChannel">GIOChannel</link> *channel,

612

590

613

591

<para>

614

592

Flushes the write buffer for the GIOChannel.</para>

615

593

<para>

616

617

594

</para><variablelist role="params">

618

<varlistentry><term><parameter>channel</parameter> :</term>

595

<varlistentry><term><parameter>channel</parameter> :</term>

619

596

<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>

620

597

</simpara></listitem></varlistentry>

621

<varlistentry><term><parameter>error</parameter> :</term>

598

<varlistentry><term><parameter>error</parameter> :</term>

622

599

<listitem><simpara> location to store an error of type <link linkend="GIOChannelError"><type>GIOChannelError</type></link>

623

600

</simpara></listitem></varlistentry>

624

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation: One of

625

626

601

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation: One of

602

603

627

604

</simpara></listitem></varlistentry>

628

605

</variablelist></refsect2>

629

630

<title><anchor id="g-io-channel-seek-position" role="function"/>g_io_channel_seek_position ()</title>

631

<indexterm><primary>g_io_channel_seek_position</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_seek_position (<link linkend="GIOChannel">GIOChannel</link> *channel,

606

607

<title>g_io_channel_seek_position ()</title>

608

<indexterm zone="g-io-channel-seek-position"><primary sortas="g_io_channel_seek_position">g_io_channel_seek_position</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_seek_position (<link linkend="GIOChannel">GIOChannel</link> *channel,

632

609

633

610

634

611

635

612

<para>

636

613

Replacement for <link linkend="g-io-channel-seek"><function>g_io_channel_seek()</function></link> with the new API.</para>

637

614

<para>

638

639

615

</para><variablelist role="params">

640

<varlistentry><term><parameter>channel</parameter> :</term>

616

<varlistentry><term><parameter>channel</parameter> :</term>

641

617

<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>

642

618

</simpara></listitem></varlistentry>

643

<varlistentry><term><parameter>offset</parameter> :</term>

619

<varlistentry><term><parameter>offset</parameter> :</term>

644

620

<listitem><simpara> The offset in bytes from the position specified by <parameter>type</parameter>

645

621

</simpara></listitem></varlistentry>

646

647

<listitem><simpara> a <link linkend="GSeekType"><type>GSeekType</type></link>. The type <link linkend="G-SEEK-CUR:CAPS"><literal>G_SEEK_CUR</literal></link> is only allowed in those

622

623

<listitem><simpara> a <link linkend="GSeekType"><type>GSeekType</type></link>. The type <link linkend="G-SEEK-CUR--CAPS"><literal>G_SEEK_CUR</literal></link> is only allowed in those

648

624

cases where a call to <link linkend="g-io-channel-set-encoding"><function>g_io_channel_set_encoding()</function></link>

649

625

is allowed. See the documentation for

650

626

651

627

</simpara></listitem></varlistentry>

652

<varlistentry><term><parameter>error</parameter> :</term>

628

<varlistentry><term><parameter>error</parameter> :</term>

653

629

<listitem><simpara> A location to return an error of type <link linkend="GIOChannelError"><type>GIOChannelError</type></link>

654

630

</simpara></listitem></varlistentry>

655

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation.

631

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation.

656

632

</simpara></listitem></varlistentry>

657

633

</variablelist></refsect2>

658

659

<title><anchor id="GSeekType" role="enum"/>enum GSeekType</title>

660

<indexterm><primary>GSeekType</primary></indexterm><programlisting>typedef enum

634

635

<title>enum GSeekType</title>

636

<indexterm zone="GSeekType"><primary sortas="GSeekType">GSeekType</primary></indexterm><programlisting>typedef enum

661

637

{

662

638

G_SEEK_CUR,

663

639

G_SEEK_SET,

668

644

An enumeration specifying the base position for a <link linkend="g-io-channel-seek-position"><function>g_io_channel_seek_position()</function></link>

669

645

operation.

670

646

</para><variablelist role="enum">

671

672

647

648

673

649

<listitem><simpara>the current position in the file.

674

650

</simpara></listitem>

675

651

</varlistentry>

676

677

652

653

678

654

<listitem><simpara>the start of the file.

679

655

</simpara></listitem>

680

656

</varlistentry>

681

682

657

658

683

659

<listitem><simpara>the end of the file.

684

685

660

</simpara></listitem>

686

661

</varlistentry>

687

662

</variablelist></refsect2>

688

689

<title><anchor id="g-io-channel-shutdown" role="function"/>g_io_channel_shutdown ()</title>

690

<indexterm><primary>g_io_channel_shutdown</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_shutdown (<link linkend="GIOChannel">GIOChannel</link> *channel,

663

664

<title>g_io_channel_shutdown ()</title>

665

<indexterm zone="g-io-channel-shutdown"><primary sortas="g_io_channel_shutdown">g_io_channel_shutdown</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_shutdown (<link linkend="GIOChannel">GIOChannel</link> *channel,

691

666

692

667

693

668

<para>

694

669

Close an IO channel. Any pending data to be written will be

695

flushed if <parameter>flush</parameter> is <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>. The channel will not be freed until the

670

flushed if <parameter>flush</parameter> is <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>. The channel will not be freed until the

696

671

last reference is dropped using <link linkend="g-io-channel-unref"><function>g_io_channel_unref()</function></link>.</para>

697

672

<para>

698

699

673

</para><variablelist role="params">

700

<varlistentry><term><parameter>channel</parameter> :</term>

674

<varlistentry><term><parameter>channel</parameter> :</term>

701

675

<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>

702

676

</simpara></listitem></varlistentry>

703

<varlistentry><term><parameter>flush</parameter> :</term>

704

<listitem><simpara> if <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>, flush pending

677

<varlistentry><term><parameter>flush</parameter> :</term>

678

<listitem><simpara> if <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, flush pending

705

679

</simpara></listitem></varlistentry>

706

680

707

681

<listitem><simpara> location to store a <link linkend="GIOChannelError"><type>GIOChannelError</type></link>

708

682

</simpara></listitem></varlistentry>

709

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation.

683

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation.

710

684

</simpara></listitem></varlistentry>

711

685

</variablelist></refsect2>

712

713

<title><anchor id="GIOStatus" role="enum"/>enum GIOStatus</title>

714

<indexterm><primary>GIOStatus</primary></indexterm><programlisting>typedef enum

686

687

<title>enum GIOStatus</title>

688

<indexterm zone="GIOStatus"><primary sortas="GIOStatus">GIOStatus</primary></indexterm><programlisting>typedef enum

715

689

{

716

690

G_IO_STATUS_ERROR,

717

691

G_IO_STATUS_NORMAL,

720

694

} GIOStatus;

721

695

</programlisting>

722

696

<para>

723

Stati returned by most of the <link linkend="GIOFuncs"><type>GIOFuncs</type></link> functions.

697

Stati returned by most of the <link linkend="GIOFuncs"><type>GIOFuncs</type></link> functions.

724

698

</para><variablelist role="enum">

725

726

<term><anchor id="G-IO-STATUS-ERROR:CAPS" role="constant"/><literal>G_IO_STATUS_ERROR</literal></term>

699

700

<term><literal>G_IO_STATUS_ERROR</literal></term>

727

701

<listitem><simpara>An error occurred.

728

702

</simpara></listitem>

729

703

</varlistentry>

730

731

<term><anchor id="G-IO-STATUS-NORMAL:CAPS" role="constant"/><literal>G_IO_STATUS_NORMAL</literal></term>

704

705

<term><literal>G_IO_STATUS_NORMAL</literal></term>

732

706

<listitem><simpara>Success.

733

707

</simpara></listitem>

734

708

</varlistentry>

735

736

<term><anchor id="G-IO-STATUS-EOF:CAPS" role="constant"/><literal>G_IO_STATUS_EOF</literal></term>

709

710

<term><literal>G_IO_STATUS_EOF</literal></term>

737

711

<listitem><simpara>End of file.

738

712

</simpara></listitem>

739

713

</varlistentry>

740

741

<term><anchor id="G-IO-STATUS-AGAIN:CAPS" role="constant"/><literal>G_IO_STATUS_AGAIN</literal></term>

714

715

<term><literal>G_IO_STATUS_AGAIN</literal></term>

742

716

<listitem><simpara>Resource temporarily unavailable.

743

744

717

</simpara></listitem>

745

718

</varlistentry>

746

719

</variablelist></refsect2>

747

748

<title><anchor id="GIOChannelError" role="enum"/>enum GIOChannelError</title>

749

<indexterm><primary>GIOChannelError</primary></indexterm><programlisting>typedef enum

720

721

<title>enum GIOChannelError</title>

722

<indexterm zone="GIOChannelError"><primary sortas="GIOChannelError">GIOChannelError</primary></indexterm><programlisting>typedef enum

750

723

{

751

724

/* Derived from errno */

752

725

G_IO_CHANNEL_ERROR_FBIG,

764

737

<para>

765

738

Error codes returned by <link linkend="GIOChannel"><type>GIOChannel</type></link> operations.

766

739

</para><variablelist role="enum">

767

768

<term><anchor id="G-IO-CHANNEL-ERROR-FBIG:CAPS" role="constant"/><literal>G_IO_CHANNEL_ERROR_FBIG</literal></term>

740

741

<term><literal>G_IO_CHANNEL_ERROR_FBIG</literal></term>

769

742

<listitem><simpara>File too large.

770

743

</simpara></listitem>

771

744

</varlistentry>

772

773

<term><anchor id="G-IO-CHANNEL-ERROR-INVAL:CAPS" role="constant"/><literal>G_IO_CHANNEL_ERROR_INVAL</literal></term>

745

746

<term><literal>G_IO_CHANNEL_ERROR_INVAL</literal></term>

774

747

<listitem><simpara>Invalid argument.

775

748

</simpara></listitem>

776

749

</varlistentry>

777

778

<term><anchor id="G-IO-CHANNEL-ERROR-IO:CAPS" role="constant"/><literal>G_IO_CHANNEL_ERROR_IO</literal></term>

750

751

<term><literal>G_IO_CHANNEL_ERROR_IO</literal></term>

779

752

<listitem><simpara>IO error.

780

753

</simpara></listitem>

781

754

</varlistentry>

782

783

<term><anchor id="G-IO-CHANNEL-ERROR-ISDIR:CAPS" role="constant"/><literal>G_IO_CHANNEL_ERROR_ISDIR</literal></term>

755

756

<term><literal>G_IO_CHANNEL_ERROR_ISDIR</literal></term>

784

757

<listitem><simpara>File is a directory.

785

758

</simpara></listitem>

786

759

</varlistentry>

787

788

<term><anchor id="G-IO-CHANNEL-ERROR-NOSPC:CAPS" role="constant"/><literal>G_IO_CHANNEL_ERROR_NOSPC</literal></term>

760

761

<term><literal>G_IO_CHANNEL_ERROR_NOSPC</literal></term>

789

762

<listitem><simpara>No space left on device.

790

763

</simpara></listitem>

791

764

</varlistentry>

792

793

<term><anchor id="G-IO-CHANNEL-ERROR-NXIO:CAPS" role="constant"/><literal>G_IO_CHANNEL_ERROR_NXIO</literal></term>

765

766

<term><literal>G_IO_CHANNEL_ERROR_NXIO</literal></term>

794

767

<listitem><simpara>No such device or address.

795

768

</simpara></listitem>

796

769

</varlistentry>

797

798

<term><anchor id="G-IO-CHANNEL-ERROR-OVERFLOW:CAPS" role="constant"/><literal>G_IO_CHANNEL_ERROR_OVERFLOW</literal></term>

770

771

<term><literal>G_IO_CHANNEL_ERROR_OVERFLOW</literal></term>

799

772

<listitem><simpara>Value too large for defined datatype.

800

773

</simpara></listitem>

801

774

</varlistentry>

802

803

<term><anchor id="G-IO-CHANNEL-ERROR-PIPE:CAPS" role="constant"/><literal>G_IO_CHANNEL_ERROR_PIPE</literal></term>

775

776

<term><literal>G_IO_CHANNEL_ERROR_PIPE</literal></term>

804

777

<listitem><simpara>Broken pipe.

805

778

</simpara></listitem>

806

779

</varlistentry>

807

808

<term><anchor id="G-IO-CHANNEL-ERROR-FAILED:CAPS" role="constant"/><literal>G_IO_CHANNEL_ERROR_FAILED</literal></term>

780

781

<term><literal>G_IO_CHANNEL_ERROR_FAILED</literal></term>

809

782

<listitem><simpara>Some other error.

810

811

783

</simpara></listitem>

812

784

</varlistentry>

813

785

</variablelist></refsect2>

814

815

<title><anchor id="G-IO-CHANNEL-ERROR:CAPS" role="macro"/>G_IO_CHANNEL_ERROR</title>

816

<indexterm><primary>G_IO_CHANNEL_ERROR</primary></indexterm><programlisting>#define G_IO_CHANNEL_ERROR g_io_channel_error_quark()

786

787

<title>G_IO_CHANNEL_ERROR</title>

788

<indexterm zone="G-IO-CHANNEL-ERROR--CAPS"><primary sortas="G_IO_CHANNEL_ERROR">G_IO_CHANNEL_ERROR</primary></indexterm><programlisting>#define G_IO_CHANNEL_ERROR g_io_channel_error_quark()

817

789

</programlisting>

818

790

<para>

819

791

Error domain for <link linkend="GIOChannel"><type>GIOChannel</type></link> operations. Errors in this domain will

820

792

be from the <link linkend="GIOChannelError"><type>GIOChannelError</type></link> enumeration. See <link linkend="GError"><type>GError</type></link> for information on

821

793

error domains.

822

794

</para></refsect2>

823

824

<title><anchor id="g-io-channel-error-from-errno" role="function"/>g_io_channel_error_from_errno ()</title>

825

<indexterm><primary>g_io_channel_error_from_errno</primary></indexterm><programlisting><link linkend="GIOChannelError">GIOChannelError</link> g_io_channel_error_from_errno (<link linkend="gint">gint</link> en);</programlisting>

795

796

<title>g_io_channel_error_from_errno ()</title>

797

<indexterm zone="g-io-channel-error-from-errno"><primary sortas="g_io_channel_error_from_errno">g_io_channel_error_from_errno</primary></indexterm><programlisting><link linkend="GIOChannelError">GIOChannelError</link> g_io_channel_error_from_errno (<link linkend="gint">gint</link> en);</programlisting>

826

798

<para>

827

799

Converts an <literal>errno</literal> error number to a <link linkend="GIOChannelError"><type>GIOChannelError</type></link>.</para>

828

800

<para>

829

830

801

</para><variablelist role="params">

831

832

<listitem><simpara> an <literal>errno</literal> error number, e.g. <link linkend="EINVAL:CAPS"><literal>EINVAL</literal></link>

802

803

<listitem><simpara> an <literal>errno</literal> error number, e.g. <link linkend="EINVAL--CAPS"><literal>EINVAL</literal></link>

833

804

</simpara></listitem></varlistentry>

834

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a <link linkend="GIOChannelError"><type>GIOChannelError</type></link> error number, e.g.

835

805

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a <link linkend="GIOChannelError"><type>GIOChannelError</type></link> error number, e.g.

806

836

807

</simpara></listitem></varlistentry>

837

808

</variablelist></refsect2>

838

839

<title><anchor id="g-io-channel-ref" role="function"/>g_io_channel_ref ()</title>

840

<indexterm><primary>g_io_channel_ref</primary></indexterm><programlisting><link linkend="GIOChannel">GIOChannel</link>* g_io_channel_ref (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>

809

810

<title>g_io_channel_ref ()</title>

811

<indexterm zone="g-io-channel-ref"><primary sortas="g_io_channel_ref">g_io_channel_ref</primary></indexterm><programlisting><link linkend="GIOChannel">GIOChannel</link> * g_io_channel_ref (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>

841

812

<para>

842

813

Increments the reference count of a <link linkend="GIOChannel"><type>GIOChannel</type></link>.

843

814

</para><variablelist role="params">

844

<varlistentry><term><parameter>channel</parameter> :</term>

815

<varlistentry><term><parameter>channel</parameter> :</term>

845

816

<listitem><simpara>a <link linkend="GIOChannel"><type>GIOChannel</type></link>.

846

817

</simpara></listitem></varlistentry>

847

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the <parameter>channel</parameter> that was passed in (since 2.6)

848

849

818

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the <parameter>channel</parameter> that was passed in (since 2.6)

850

819

</simpara></listitem></varlistentry>

851

820

</variablelist></refsect2>

852

853

<title><anchor id="g-io-channel-unref" role="function"/>g_io_channel_unref ()</title>

854

<indexterm><primary>g_io_channel_unref</primary></indexterm><programlisting><link linkend="void">void</link> g_io_channel_unref (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>

821

822

<title>g_io_channel_unref ()</title>

823

<indexterm zone="g-io-channel-unref"><primary sortas="g_io_channel_unref">g_io_channel_unref</primary></indexterm><programlisting><link linkend="void">void</link> g_io_channel_unref (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>

855

824

<para>

856

825

Decrements the reference count of a <link linkend="GIOChannel"><type>GIOChannel</type></link>.

857

826

</para><variablelist role="params">

858

<varlistentry><term><parameter>channel</parameter> :</term>

827

<varlistentry><term><parameter>channel</parameter> :</term>

859

828

<listitem><simpara>a <link linkend="GIOChannel"><type>GIOChannel</type></link>.

860

861

862

829

</simpara></listitem></varlistentry>

863

830

</variablelist></refsect2>

864

865

<title><anchor id="g-io-create-watch" role="function"/>g_io_create_watch ()</title>

866

<indexterm><primary>g_io_create_watch</primary></indexterm><programlisting><link linkend="GSource">GSource</link>* g_io_create_watch (<link linkend="GIOChannel">GIOChannel</link> *channel,

831

832

<title>g_io_create_watch ()</title>

833

<indexterm zone="g-io-create-watch"><primary sortas="g_io_create_watch">g_io_create_watch</primary></indexterm><programlisting><link linkend="GSource">GSource</link> * g_io_create_watch (<link linkend="GIOChannel">GIOChannel</link> *channel,

867

834

868

835

<para>

869

836

Creates a <link linkend="GSource"><type>GSource</type></link> that's dispatched when <parameter>condition</parameter> is met for the given

870

<parameter>channel</parameter>. For example, if condition is <link linkend="G-IO-IN:CAPS"><type>G_IO_IN</type></link>, the source will be dispatched

837

<parameter>channel</parameter>. For example, if condition is <link linkend="G-IO-IN--CAPS"><type>G_IO_IN</type></link>, the source will be dispatched

871

838

when there's data available for reading. <link linkend="g-io-add-watch"><function>g_io_add_watch()</function></link> is a simpler

872

839

interface to this same functionality, for the case where you want to add the

873

840

source to the default main loop at the default priority.

877

844

puts the socket in non-blocking mode. This is a side-effect of the

878

845

implementation and unavoidable.

879

846

</para><variablelist role="params">

880

<varlistentry><term><parameter>channel</parameter> :</term>

847

<varlistentry><term><parameter>channel</parameter> :</term>

881

848

<listitem><simpara>a <link linkend="GIOChannel"><type>GIOChannel</type></link> to watch

882

849

</simpara></listitem></varlistentry>

883

<varlistentry><term><parameter>condition</parameter> :</term>

850

<varlistentry><term><parameter>condition</parameter> :</term>

884

851

<listitem><simpara>conditions to watch for

885

852

</simpara></listitem></varlistentry>

886

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a new <link linkend="GSource"><type>GSource</type></link>

887

888

853

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a new <link linkend="GSource"><type>GSource</type></link>

889

854

</simpara></listitem></varlistentry>

890

855

</variablelist></refsect2>

891

892

<title><anchor id="g-io-add-watch" role="function"/>g_io_add_watch ()</title>

893

<indexterm><primary>g_io_add_watch</primary></indexterm><programlisting><link linkend="guint">guint</link> g_io_add_watch (<link linkend="GIOChannel">GIOChannel</link> *channel,

856

857

<title>g_io_add_watch ()</title>

858

<indexterm zone="g-io-add-watch"><primary sortas="g_io_add_watch">g_io_add_watch</primary></indexterm><programlisting><link linkend="guint">guint</link> g_io_add_watch (<link linkend="GIOChannel">GIOChannel</link> *channel,

894

859

895

860

896

861

899

864

900

865

with the default priority.

901

866

</para><variablelist role="params">

902

<varlistentry><term><parameter>channel</parameter> :</term>

867

<varlistentry><term><parameter>channel</parameter> :</term>

903

868

<listitem><simpara>a <link linkend="GIOChannel"><type>GIOChannel</type></link>

904

869

</simpara></listitem></varlistentry>

905

<varlistentry><term><parameter>condition</parameter> :</term>

870

<varlistentry><term><parameter>condition</parameter> :</term>

906

871

<listitem><simpara>the condition to watch for

907

872

</simpara></listitem></varlistentry>

908

873

909

874

<listitem><simpara>the function to call when the condition is satisfied

910

875

</simpara></listitem></varlistentry>

911

876

912

877

913

878

</simpara></listitem></varlistentry>

914

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the event source id

915

916

879

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the event source id

917

880

</simpara></listitem></varlistentry>

918

881

</variablelist></refsect2>

919

920

<title><anchor id="g-io-add-watch-full" role="function"/>g_io_add_watch_full ()</title>

921

<indexterm><primary>g_io_add_watch_full</primary></indexterm><programlisting><link linkend="guint">guint</link> g_io_add_watch_full (<link linkend="GIOChannel">GIOChannel</link> *channel,

882

883

<title>g_io_add_watch_full ()</title>

884

<indexterm zone="g-io-add-watch-full"><primary sortas="g_io_add_watch_full">g_io_add_watch_full</primary></indexterm><programlisting><link linkend="guint">guint</link> g_io_add_watch_full (<link linkend="GIOChannel">GIOChannel</link> *channel,

922

885

923

886

924

887

929

892

930

893

with the given priority.

931

894

</para><variablelist role="params">

932

<varlistentry><term><parameter>channel</parameter> :</term>

895

<varlistentry><term><parameter>channel</parameter> :</term>

933

896

<listitem><simpara>a <link linkend="GIOChannel"><type>GIOChannel</type></link>

934

897

</simpara></listitem></varlistentry>

935

<varlistentry><term><parameter>priority</parameter> :</term>

898

<varlistentry><term><parameter>priority</parameter> :</term>

936

899

<listitem><simpara>the priority of the <link linkend="GIOChannel"><type>GIOChannel</type></link> source

937

900

</simpara></listitem></varlistentry>

938

<varlistentry><term><parameter>condition</parameter> :</term>

901

<varlistentry><term><parameter>condition</parameter> :</term>

939

902

<listitem><simpara>the condition to watch for

940

903

</simpara></listitem></varlistentry>

941

904

942

905

<listitem><simpara>the function to call when the condition is satisfied

943

906

</simpara></listitem></varlistentry>

944

907

945

908

946

909

</simpara></listitem></varlistentry>

947

<varlistentry><term><parameter>notify</parameter> :</term>

910

<varlistentry><term><parameter>notify</parameter> :</term>

948

911

<listitem><simpara>the function to call when the source is removed

949

912

</simpara></listitem></varlistentry>

950

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the event source id

951

952

913

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the event source id

953

914

</simpara></listitem></varlistentry>

954

915

</variablelist></refsect2>

955

956

<title><anchor id="GIOCondition" role="enum"/>enum GIOCondition</title>

957

<indexterm><primary>GIOCondition</primary></indexterm><programlisting>typedef enum

916

917

<title>enum GIOCondition</title>

918

<indexterm zone="GIOCondition"><primary sortas="GIOCondition">GIOCondition</primary></indexterm><programlisting>typedef enum

958

919

{

959

920

G_IO_IN GLIB_SYSDEF_POLLIN,

960

921

G_IO_OUT GLIB_SYSDEF_POLLOUT,

965

926

} GIOCondition;

966

927

</programlisting>

967

928

<para>

968

A bitwise combination representing a condition to watch for on

929

A bitwise combination representing a condition to watch for on

969

930

an event source.

970

931

</para><variablelist role="enum">

971

972

932

933

973

934

<listitem><simpara>There is data to read.

974

935

</simpara></listitem>

975

936

</varlistentry>

976

977

937

938

978

939

<listitem><simpara>Data can be written (without blocking).

979

940

</simpara></listitem>

980

941

</varlistentry>

981

982

942

943

983

944

<listitem><simpara>There is urgent data to read.

984

945

</simpara></listitem>

985

946

</varlistentry>

986

987

947

948

988

949

<listitem><simpara>Error condition.

989

950

</simpara></listitem>

990

951

</varlistentry>

991

992

952

953

993

954

<listitem><simpara>Hung up (the connection has been broken, usually for pipes

994

955

and sockets).

995

956

</simpara></listitem>

996

957

</varlistentry>

997

998

958

959

999

960

<listitem><simpara>Invalid request. The file descriptor is not open.

1000

1001

961

</simpara></listitem>

1002

962

</varlistentry>

1003

963

</variablelist></refsect2>

1004

1005

<title><anchor id="GIOFunc" role="function"/>GIOFunc ()</title>

1006

<indexterm><primary>GIOFunc</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> (*GIOFunc) (<link linkend="GIOChannel">GIOChannel</link> *source,

964

965

<title>GIOFunc ()</title>

966

<indexterm zone="GIOFunc"><primary sortas="GIOFunc">GIOFunc</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> (*GIOFunc) (<link linkend="GIOChannel">GIOChannel</link> *source,

1007

967

1008

968

1009

969

<para>

1010

970

Specifies the type of function passed to <link linkend="g-io-add-watch"><function>g_io_add_watch()</function></link> or

1011

971

1012

972

condition on a <link linkend="GIOChannel"><type>GIOChannel</type></link> is satisfied.

1013

973

</para><variablelist role="params">

1014

<varlistentry><term><parameter>source</parameter> :</term>

974

<varlistentry><term><parameter>source</parameter> :</term>

1015

975

<listitem><simpara>the <link linkend="GIOChannel"><type>GIOChannel</type></link> event source

1016

976

</simpara></listitem></varlistentry>

1017

<varlistentry><term><parameter>condition</parameter> :</term>

977

<varlistentry><term><parameter>condition</parameter> :</term>

1018

978

<listitem><simpara>the condition which has been satisfied

1019

979

</simpara></listitem></varlistentry>

1020

980

1021

981

<listitem><simpara>user data set in <link linkend="g-io-add-watch"><function>g_io_add_watch()</function></link> or <link linkend="g-io-add-watch-full"><function>g_io_add_watch_full()</function></link>

1022

982

</simpara></listitem></varlistentry>

1023

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the function should return <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if the event source

983

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the function should return <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if the event source

1024

984

should be removed

1025

1026

1027

985

</simpara></listitem></varlistentry>

1028

986

</variablelist></refsect2>

1029

1030

<title><anchor id="GIOFuncs" role="struct"/>GIOFuncs</title>

1031

<indexterm><primary>GIOFuncs</primary></indexterm><programlisting>typedef struct {

987

988

<title>GIOFuncs</title>

989

<indexterm zone="GIOFuncs"><primary sortas="GIOFuncs">GIOFuncs</primary></indexterm><programlisting>typedef struct {

1032

990

GIOStatus (*io_read) (GIOChannel *channel,

1033

991

gchar *buf,

1034

992

gsize count,

1055

1013

} GIOFuncs;

1056

1014

</programlisting>

1057

1015

<para>

1058

A table of functions used to handle different types of <link linkend="GIOChannel"><type>GIOChannel</type></link>

1016

A table of functions used to handle different types of <link linkend="GIOChannel"><type>GIOChannel</type></link>

1059

1017

in a generic way.

1060

1018

</para></refsect2>

1061

1062

<title><anchor id="g-io-channel-get-buffer-size" role="function"/>g_io_channel_get_buffer_size ()</title>

1063

<indexterm><primary>g_io_channel_get_buffer_size</primary></indexterm><programlisting><link linkend="gsize">gsize</link> g_io_channel_get_buffer_size (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>

1019

1020

<title>g_io_channel_get_buffer_size ()</title>

1021

<indexterm zone="g-io-channel-get-buffer-size"><primary sortas="g_io_channel_get_buffer_size">g_io_channel_get_buffer_size</primary></indexterm><programlisting><link linkend="gsize">gsize</link> g_io_channel_get_buffer_size (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>

1064

1022

<para>

1065

1023

Gets the buffer size.</para>

1066

1024

<para>

1067

1068

1025

</para><variablelist role="params">

1069

<varlistentry><term><parameter>channel</parameter> :</term>

1026

<varlistentry><term><parameter>channel</parameter> :</term>

1070

1027

<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>

1071

1028

</simpara></listitem></varlistentry>

1072

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the size of the buffer.

1029

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the size of the buffer.

1073

1030

</simpara></listitem></varlistentry>

1074

1031

</variablelist></refsect2>

1075

1076

<title><anchor id="g-io-channel-set-buffer-size" role="function"/>g_io_channel_set_buffer_size ()</title>

1077

<indexterm><primary>g_io_channel_set_buffer_size</primary></indexterm><programlisting><link linkend="void">void</link> g_io_channel_set_buffer_size (<link linkend="GIOChannel">GIOChannel</link> *channel,

1032

1033

<title>g_io_channel_set_buffer_size ()</title>

1034

<indexterm zone="g-io-channel-set-buffer-size"><primary sortas="g_io_channel_set_buffer_size">g_io_channel_set_buffer_size</primary></indexterm><programlisting><link linkend="void">void</link> g_io_channel_set_buffer_size (<link linkend="GIOChannel">GIOChannel</link> *channel,

1078

1035

1079

1036

<para>

1080

1037

Sets the buffer size.</para>

1081

1038

<para>

1082

1083

1039

</para><variablelist role="params">

1084

<varlistentry><term><parameter>channel</parameter> :</term>

1040

<varlistentry><term><parameter>channel</parameter> :</term>

1085

1041

<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>

1086

1042

</simpara></listitem></varlistentry>

1087

1043

1088

1044

<listitem><simpara> the size of the buffer, or 0 to let GLib pick a good size

1089

1045

</simpara></listitem></varlistentry>

1090

1046

</variablelist></refsect2>

1091

1092

<title><anchor id="g-io-channel-get-buffer-condition" role="function"/>g_io_channel_get_buffer_condition ()</title>

1093

<indexterm><primary>g_io_channel_get_buffer_condition</primary></indexterm><programlisting><link linkend="GIOCondition">GIOCondition</link> g_io_channel_get_buffer_condition (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>

1047

1048

<title>g_io_channel_get_buffer_condition ()</title>

1049

<indexterm zone="g-io-channel-get-buffer-condition"><primary sortas="g_io_channel_get_buffer_condition">g_io_channel_get_buffer_condition</primary></indexterm><programlisting><link linkend="GIOCondition">GIOCondition</link> g_io_channel_get_buffer_condition (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>

1094

1050

<para>

1095

1051

This function returns a <link linkend="GIOCondition"><type>GIOCondition</type></link> depending on whether there

1096

1052

is data to be read/space to write data in the internal buffers in

1097

the <link linkend="GIOChannel"><type>GIOChannel</type></link>. Only the flags <link linkend="G-IO-IN:CAPS"><literal>G_IO_IN</literal></link> and <link linkend="G-IO-OUT:CAPS"><literal>G_IO_OUT</literal></link> may be set.</para>

1053

the <link linkend="GIOChannel"><type>GIOChannel</type></link>. Only the flags <link linkend="G-IO-IN--CAPS"><literal>G_IO_IN</literal></link> and <link linkend="G-IO-OUT--CAPS"><literal>G_IO_OUT</literal></link> may be set.</para>

1098

1054

<para>

1099

1100

1055

</para><variablelist role="params">

1101

<varlistentry><term><parameter>channel</parameter> :</term>

1056

<varlistentry><term><parameter>channel</parameter> :</term>

1102

1057

<listitem><simpara> A <link linkend="GIOChannel"><type>GIOChannel</type></link>

1103

1058

</simpara></listitem></varlistentry>

1104

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A <link linkend="GIOCondition"><type>GIOCondition</type></link>

1059

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A <link linkend="GIOCondition"><type>GIOCondition</type></link>

1105

1060

</simpara></listitem></varlistentry>

1106

1061

</variablelist></refsect2>

1107

1108

<title><anchor id="g-io-channel-get-flags" role="function"/>g_io_channel_get_flags ()</title>

1109

<indexterm><primary>g_io_channel_get_flags</primary></indexterm><programlisting><link linkend="GIOFlags">GIOFlags</link> g_io_channel_get_flags (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>

1062

1063

<title>g_io_channel_get_flags ()</title>

1064

<indexterm zone="g-io-channel-get-flags"><primary sortas="g_io_channel_get_flags">g_io_channel_get_flags</primary></indexterm><programlisting><link linkend="GIOFlags">GIOFlags</link> g_io_channel_get_flags (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>

1110

1065

<para>

1111

1066

Gets the current flags for a <link linkend="GIOChannel"><type>GIOChannel</type></link>, including read-only

1112

flags such as <link linkend="G-IO-FLAG-IS-READABLE:CAPS"><literal>G_IO_FLAG_IS_READABLE</literal></link>.

1067

flags such as <link linkend="G-IO-FLAG-IS-READABLE--CAPS"><literal>G_IO_FLAG_IS_READABLE</literal></link>.

1113

1068

</para>

1114

1069

<para>

1115

The values of the flags <link linkend="G-IO-FLAG-IS-READABLE:CAPS"><literal>G_IO_FLAG_IS_READABLE</literal></link> and <link linkend="G-IO-FLAG-IS-WRITEABLE:CAPS"><literal>G_IO_FLAG_IS_WRITEABLE</literal></link>

1070

The values of the flags <link linkend="G-IO-FLAG-IS-READABLE--CAPS"><literal>G_IO_FLAG_IS_READABLE</literal></link> and <link linkend="G-IO-FLAG-IS-WRITEABLE--CAPS"><literal>G_IO_FLAG_IS_WRITEABLE</literal></link>

1116

1071

are cached for internal use by the channel when it is created.

1117

1072

If they should change at some later point (e.g. partial shutdown

1118

1073

of a socket with the UNIX <link linkend="shutdown"><function>shutdown()</function></link> function), the user

1119

1074

should immediately call <link linkend="g-io-channel-get-flags"><function>g_io_channel_get_flags()</function></link> to update

1120

1075

the internal values of these flags.</para>

1121

1076

<para>

1122

1123

1077

</para><variablelist role="params">

1124

<varlistentry><term><parameter>channel</parameter> :</term>

1078

<varlistentry><term><parameter>channel</parameter> :</term>

1125

1079

<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>

1126

1080

</simpara></listitem></varlistentry>

1127

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the flags which are set on the channel

1081

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the flags which are set on the channel

1128

1082

</simpara></listitem></varlistentry>

1129

1083

</variablelist></refsect2>

1130

1131

<title><anchor id="g-io-channel-set-flags" role="function"/>g_io_channel_set_flags ()</title>

1132

<indexterm><primary>g_io_channel_set_flags</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_set_flags (<link linkend="GIOChannel">GIOChannel</link> *channel,

1084

1085

<title>g_io_channel_set_flags ()</title>

1086

<indexterm zone="g-io-channel-set-flags"><primary sortas="g_io_channel_set_flags">g_io_channel_set_flags</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_set_flags (<link linkend="GIOChannel">GIOChannel</link> *channel,

1133

1087

1134

1088

1135

1089

<para>

1136

Sets the (writeable) flags in <parameter>channel</parameter> to (<parameter>flags</parameter> & <link linkend="G-IO-CHANNEL-SET-MASK:CAPS"><literal>G_IO_CHANNEL_SET_MASK</literal></link>).</para>

1090

Sets the (writeable) flags in <parameter>channel</parameter> to (<parameter>flags</parameter> & <link linkend="G-IO-CHANNEL-SET-MASK--CAPS"><literal>G_IO_CHANNEL_SET_MASK</literal></link>).</para>

1137

1091

<para>

1138

1139

1092

</para><variablelist role="params">

1140

<varlistentry><term><parameter>channel</parameter> :</term>

1093

<varlistentry><term><parameter>channel</parameter> :</term>

1141

1094

<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>

1142

1095

</simpara></listitem></varlistentry>

1143

<varlistentry><term><parameter>flags</parameter> :</term>

1096

<varlistentry><term><parameter>flags</parameter> :</term>

1144

1097

<listitem><simpara> the flags to set on the IO channel

1145

1098

</simpara></listitem></varlistentry>

1146

<varlistentry><term><parameter>error</parameter> :</term>

1099

<varlistentry><term><parameter>error</parameter> :</term>

1147

1100

<listitem><simpara> A location to return an error of type <link linkend="GIOChannelError"><type>GIOChannelError</type></link>

1148

1101

</simpara></listitem></varlistentry>

1149

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation.

1102

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation.

1150

1103

</simpara></listitem></varlistentry>

1151

1104

</variablelist></refsect2>

1152

1153

<title><anchor id="GIOFlags" role="enum"/>enum GIOFlags</title>

1154

<indexterm><primary>GIOFlags</primary></indexterm><programlisting>typedef enum

1105

1106

<title>enum GIOFlags</title>

1107

<indexterm zone="GIOFlags"><primary sortas="GIOFlags">GIOFlags</primary></indexterm><programlisting>typedef enum

1155

1108

{

1156

1109

G_IO_FLAG_APPEND = 1 << 0,

1157

1110

G_IO_FLAG_NONBLOCK = 1 << 1,

1166

1119

<para>

1167

1120

Specifies properties of a <link linkend="GIOChannel"><type>GIOChannel</type></link>. Some of the flags can only

1168

1121

be read with <link linkend="g-io-channel-get-flags"><function>g_io_channel_get_flags()</function></link>, but not changed with

1169

1122

1170

1123

</para><variablelist role="enum">

1171

1172

<term><anchor id="G-IO-FLAG-APPEND:CAPS" role="constant"/><literal>G_IO_FLAG_APPEND</literal></term>

1173

<listitem><simpara>turns on append mode, corresponds to <link linkend="O-APPEND:CAPS"><literal>O_APPEND</literal></link>

1124

1125

<term><literal>G_IO_FLAG_APPEND</literal></term>

1126

<listitem><simpara>turns on append mode, corresponds to <link linkend="O-APPEND--CAPS"><literal>O_APPEND</literal></link>

1174

1127

(see the documentation of the UNIX <link linkend="open"><function>open()</function></link> syscall).

1175

1128

</simpara></listitem>

1176

1129

</varlistentry>

1177

1178

<term><anchor id="G-IO-FLAG-NONBLOCK:CAPS" role="constant"/><literal>G_IO_FLAG_NONBLOCK</literal></term>

1130

1131

<term><literal>G_IO_FLAG_NONBLOCK</literal></term>

1179

1132

<listitem><simpara>turns on nonblocking mode, corresponds to

1180

1133

1181

1134

syscall).

1182

1135

</simpara></listitem>

1183

1136

</varlistentry>

1184

1185

<term><anchor id="G-IO-FLAG-IS-READABLE:CAPS" role="constant"/><literal>G_IO_FLAG_IS_READABLE</literal></term>

1137

1138

<term><literal>G_IO_FLAG_IS_READABLE</literal></term>

1186

1139

<listitem><simpara>indicates that the io channel is readable.

1187

1140

This flag can not be changed.

1188

1141

</simpara></listitem>

1189

1142

</varlistentry>

1190

1191

<term><anchor id="G-IO-FLAG-IS-WRITEABLE:CAPS" role="constant"/><literal>G_IO_FLAG_IS_WRITEABLE</literal></term>

1143

1144

<term><literal>G_IO_FLAG_IS_WRITEABLE</literal></term>

1192

1145

<listitem><simpara>indicates that the io channel is writable.

1193

1146

This flag can not be changed.

1194

1147

</simpara></listitem>

1195

1148

</varlistentry>

1196

1197

<term><anchor id="G-IO-FLAG-IS-SEEKABLE:CAPS" role="constant"/><literal>G_IO_FLAG_IS_SEEKABLE</literal></term>

1149

1150

<term><literal>G_IO_FLAG_IS_SEEKABLE</literal></term>

1198

1151

<listitem><simpara>indicates that the io channel is seekable,

1199

i.e. that <link linkend="g-io-channel-seek-position"><function>g_io_channel_seek_position()</function></link> can be used on it.

1152

i.e. that <link linkend="g-io-channel-seek-position"><function>g_io_channel_seek_position()</function></link> can be used on it.

1200

1153

This flag can not be changed.

1201

1154

</simpara></listitem>

1202

1155

</varlistentry>

1203

1204

1205

1206

</simpara></listitem>

1207

</varlistentry>

1208

1209

1210

1211

</simpara></listitem>

1212

</varlistentry>

1213

1214

1215

1216

1156

1157

1158

1159

</simpara></listitem>

1160

</varlistentry>

1161

1162

1163

1164

</simpara></listitem>

1165

</varlistentry>

1166

1167

1168

1217

1169

</simpara></listitem>

1218

1170

</varlistentry>

1219

1171

</variablelist></refsect2>

1220

1221

<title><anchor id="g-io-channel-get-line-term" role="function"/>g_io_channel_get_line_term ()</title>

1222

<indexterm><primary>g_io_channel_get_line_term</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>* g_io_channel_get_line_term (<link linkend="GIOChannel">GIOChannel</link> *channel,

1172

1173

<title>g_io_channel_get_line_term ()</title>

1174

<indexterm zone="g-io-channel-get-line-term"><primary sortas="g_io_channel_get_line_term">g_io_channel_get_line_term</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>* g_io_channel_get_line_term (<link linkend="GIOChannel">GIOChannel</link> *channel,

1223

1175

1224

1176

<para>

1225

1177

This returns the string that <link linkend="GIOChannel"><type>GIOChannel</type></link> uses to determine

1226

where in the file a line break occurs. A value of <link linkend="NULL:CAPS"><literal>NULL</literal></link>

1178

where in the file a line break occurs. A value of <link linkend="NULL--CAPS"><literal>NULL</literal></link>

1227

1179

indicates autodetection.</para>

1228

1180

<para>

1229

1230

1181

</para><variablelist role="params">

1231

<varlistentry><term><parameter>channel</parameter> :</term>

1182

<varlistentry><term><parameter>channel</parameter> :</term>

1232

1183

<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>

1233

1184

</simpara></listitem></varlistentry>

1234

<varlistentry><term><parameter>length</parameter> :</term>

1185

<varlistentry><term><parameter>length</parameter> :</term>

1235

1186

<listitem><simpara> a location to return the length of the line terminator

1236

1187

</simpara></listitem></varlistentry>

1237

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The line termination string. This value

1188

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The line termination string. This value

1238

1189

is owned by GLib and must not be freed.

1239

1190

</simpara></listitem></varlistentry>

1240

1191

</variablelist></refsect2>

1241

1242

<title><anchor id="g-io-channel-set-line-term" role="function"/>g_io_channel_set_line_term ()</title>

1243

<indexterm><primary>g_io_channel_set_line_term</primary></indexterm><programlisting><link linkend="void">void</link> g_io_channel_set_line_term (<link linkend="GIOChannel">GIOChannel</link> *channel,

1192

1193

<title>g_io_channel_set_line_term ()</title>

1194

<indexterm zone="g-io-channel-set-line-term"><primary sortas="g_io_channel_set_line_term">g_io_channel_set_line_term</primary></indexterm><programlisting><link linkend="void">void</link> g_io_channel_set_line_term (<link linkend="GIOChannel">GIOChannel</link> *channel,

1244

1195

const <link linkend="gchar">gchar</link> *line_term,

1245

1196

1246

1197

<para>

1247

1198

This sets the string that <link linkend="GIOChannel"><type>GIOChannel</type></link> uses to determine

1248

1199

where in the file a line break occurs.</para>

1249

1200

<para>

1250

1251

1201

</para><variablelist role="params">

1252

<varlistentry><term><parameter>channel</parameter> :</term>

1202

<varlistentry><term><parameter>channel</parameter> :</term>

1253

1203

<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>

1254

1204

</simpara></listitem></varlistentry>

1255

1256

<listitem><simpara> The line termination string. Use <link linkend="NULL:CAPS"><literal>NULL</literal></link> for autodetect.

1205

1206

<listitem><simpara> The line termination string. Use <link linkend="NULL--CAPS"><literal>NULL</literal></link> for autodetect.

1257

1207

Autodetection breaks on "\n", "\r\n", "\r", "\0", and

1258

1208

the Unicode paragraph separator. Autodetection should

1259

1209

not be used for anything other than file-based channels.

1260

1210

</simpara></listitem></varlistentry>

1261

<varlistentry><term><parameter>length</parameter> :</term>

1211

<varlistentry><term><parameter>length</parameter> :</term>

1262

1212

<listitem><simpara> The length of the termination string. If -1 is passed, the

1263

1213

string is assumed to be nul-terminated. This option allows

1264

1214

termination strings with embedded nuls.

1265

1215

</simpara></listitem></varlistentry>

1266

1216

</variablelist></refsect2>

1267

1268

<title><anchor id="g-io-channel-get-buffered" role="function"/>g_io_channel_get_buffered ()</title>

1269

<indexterm><primary>g_io_channel_get_buffered</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_io_channel_get_buffered (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>

1217

1218

<title>g_io_channel_get_buffered ()</title>

1219

<indexterm zone="g-io-channel-get-buffered"><primary sortas="g_io_channel_get_buffered">g_io_channel_get_buffered</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_io_channel_get_buffered (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>

1270

1220

<para>

1271

1221

Returns whether <parameter>channel</parameter> is buffered.</para>

1272

1222

<para>

1273

1274

1223

</para><variablelist role="params">

1275

<varlistentry><term><parameter>channel</parameter> :</term>

1224

<varlistentry><term><parameter>channel</parameter> :</term>

1276

1225

<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>

1277

1226

</simpara></listitem></varlistentry>

1278

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the <parameter>channel</parameter> is buffered.

1227

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the <parameter>channel</parameter> is buffered.

1279

1228

</simpara></listitem></varlistentry>

1280

1229

</variablelist></refsect2>

1281

1282

<title><anchor id="g-io-channel-set-buffered" role="function"/>g_io_channel_set_buffered ()</title>

1283

<indexterm><primary>g_io_channel_set_buffered</primary></indexterm><programlisting><link linkend="void">void</link> g_io_channel_set_buffered (<link linkend="GIOChannel">GIOChannel</link> *channel,

1230

1231

<title>g_io_channel_set_buffered ()</title>

1232

<indexterm zone="g-io-channel-set-buffered"><primary sortas="g_io_channel_set_buffered">g_io_channel_set_buffered</primary></indexterm><programlisting><link linkend="void">void</link> g_io_channel_set_buffered (<link linkend="GIOChannel">GIOChannel</link> *channel,

1284

1233

1285

1234

<para>

1286

1235

The buffering state can only be set if the channel's encoding

1287

is <link linkend="NULL:CAPS"><literal>NULL</literal></link>. For any other encoding, the channel must be buffered.

1236

is <link linkend="NULL--CAPS"><literal>NULL</literal></link>. For any other encoding, the channel must be buffered.

1288

1237

</para>

1289

1238

<para>

1290

1239

A buffered channel can only be set unbuffered if the channel's

1291

1240

internal buffers have been flushed. Newly created channels or

1292

channels which have returned <link linkend="G-IO-STATUS-EOF:CAPS"><literal>G_IO_STATUS_EOF</literal></link>

1241

channels which have returned <link linkend="G-IO-STATUS-EOF--CAPS"><literal>G_IO_STATUS_EOF</literal></link>

1293

1242

not require such a flush. For write-only channels, a call to

1294

1243

1295

1244

the buffers may be flushed by a call to <link linkend="g-io-channel-seek-position"><function>g_io_channel_seek_position()</function></link>.

1296

This includes the possibility of seeking with seek type <link linkend="G-SEEK-CUR:CAPS"><literal>G_SEEK_CUR</literal></link>

1245

This includes the possibility of seeking with seek type <link linkend="G-SEEK-CUR--CAPS"><literal>G_SEEK_CUR</literal></link>

1297

1246

and an offset of zero. Note that this means that socket-based

1298

1247

channels cannot be set unbuffered once they have had data

1299

1248

read from them.

1306

1255

<para>

1307

1256

The default state of the channel is buffered.</para>

1308

1257

<para>

1309

1310

1258

</para><variablelist role="params">

1311

<varlistentry><term><parameter>channel</parameter> :</term>

1259

<varlistentry><term><parameter>channel</parameter> :</term>

1312

1260

<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>

1313

1261

</simpara></listitem></varlistentry>

1314

<varlistentry><term><parameter>buffered</parameter> :</term>

1262

<varlistentry><term><parameter>buffered</parameter> :</term>

1315

1263

<listitem><simpara> whether to set the channel buffered or unbuffered

1316

1264

</simpara></listitem></varlistentry>

1317

1265

</variablelist></refsect2>

1318

1319

<title><anchor id="g-io-channel-get-encoding" role="function"/>g_io_channel_get_encoding ()</title>

1320

<indexterm><primary>g_io_channel_get_encoding</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>* g_io_channel_get_encoding (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>

1266

1267

<title>g_io_channel_get_encoding ()</title>

1268

<indexterm zone="g-io-channel-get-encoding"><primary sortas="g_io_channel_get_encoding">g_io_channel_get_encoding</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>* g_io_channel_get_encoding (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>

1321

1269

<para>

1322

1270

Gets the encoding for the input/output of the channel.

1323

The internal encoding is always UTF-8. The encoding <link linkend="NULL:CAPS"><literal>NULL</literal></link>

1271

The internal encoding is always UTF-8. The encoding <link linkend="NULL--CAPS"><literal>NULL</literal></link>

1324

1272

makes the channel safe for binary data.</para>

1325

1273

<para>

1326

1327

1274

</para><variablelist role="params">

1328

<varlistentry><term><parameter>channel</parameter> :</term>

1275

<varlistentry><term><parameter>channel</parameter> :</term>

1329

1276

<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>

1330

1277

</simpara></listitem></varlistentry>

1331

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A string containing the encoding, this string is

1278

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A string containing the encoding, this string is

1332

1279

owned by GLib and must not be freed.

1333

1280

</simpara></listitem></varlistentry>

1334

1281

</variablelist></refsect2>

1335

1336

<title><anchor id="g-io-channel-set-encoding" role="function"/>g_io_channel_set_encoding ()</title>

1337

<indexterm><primary>g_io_channel_set_encoding</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_set_encoding (<link linkend="GIOChannel">GIOChannel</link> *channel,

1282

1283

<title>g_io_channel_set_encoding ()</title>

1284

<indexterm zone="g-io-channel-set-encoding"><primary sortas="g_io_channel_set_encoding">g_io_channel_set_encoding</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_set_encoding (<link linkend="GIOChannel">GIOChannel</link> *channel,

1338

1285

const <link linkend="gchar">gchar</link> *encoding,

1339

1286

1340

1287

<para>

1343

1290

for the external file is UTF-8.

1344

1291

</para>

1345

1292

<para>

1346

The encoding <link linkend="NULL:CAPS"><literal>NULL</literal></link> is safe to use with binary data.

1293

The encoding <link linkend="NULL--CAPS"><literal>NULL</literal></link> is safe to use with binary data.

1347

1294

</para>

1348

1295

<para>

1349

1296

The encoding can only be set if one of the following conditions

1362

1309

(This flushes all the internal buffers.)

1363

1310

</para></listitem>

1364

1311

1365

The current encoding is <link linkend="NULL:CAPS"><literal>NULL</literal></link> or UTF-8.

1312

The current encoding is <link linkend="NULL--CAPS"><literal>NULL</literal></link> or UTF-8.

1366

1313

</para></listitem>

1367

1314

1368

One of the (new API) read functions has just returned <link linkend="G-IO-STATUS-EOF:CAPS"><literal>G_IO_STATUS_EOF</literal></link>

1369

(or, in the case of <link linkend="g-io-channel-read-to-end"><function>g_io_channel_read_to_end()</function></link>, <link linkend="G-IO-STATUS-NORMAL:CAPS"><literal>G_IO_STATUS_NORMAL</literal></link>).

1315

One of the (new API) read functions has just returned <link linkend="G-IO-STATUS-EOF--CAPS"><literal>G_IO_STATUS_EOF</literal></link>

1316

(or, in the case of <link linkend="g-io-channel-read-to-end"><function>g_io_channel_read_to_end()</function></link>, <link linkend="G-IO-STATUS-NORMAL--CAPS"><literal>G_IO_STATUS_NORMAL</literal></link>).

1370

1317

</para></listitem>

1371

1318

1372

1319

One of the functions <link linkend="g-io-channel-read-chars"><function>g_io_channel_read_chars()</function></link> or

1373

1374

1375

1320

1321

1322

1376

1323

Returning one of these statuses from <link linkend="g-io-channel-read-line"><function>g_io_channel_read_line()</function></link>,

1377

1324

1378

1325

does <emphasis>not</emphasis> guarantee that the encoding can

1380

1327

</para></listitem>

1381

1328

</itemizedlist>

1382

1329

Channels which do not meet one of the above conditions cannot call

1383

1330

1384

1331

they are "seekable", cannot call <link linkend="g-io-channel-write-chars"><function>g_io_channel_write_chars()</function></link> after

1385

1332

calling one of the API "read" functions.</para>

1386

1333

<para>

1387

1388

1334

</para><variablelist role="params">

1389

<varlistentry><term><parameter>channel</parameter> :</term>

1335

<varlistentry><term><parameter>channel</parameter> :</term>

1390

1336

<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>

1391

1337

</simpara></listitem></varlistentry>

1392

<varlistentry><term><parameter>encoding</parameter> :</term>

1338

<varlistentry><term><parameter>encoding</parameter> :</term>

1393

1339

<listitem><simpara> the encoding type

1394

1340

</simpara></listitem></varlistentry>

1395

<varlistentry><term><parameter>error</parameter> :</term>

1341

<varlistentry><term><parameter>error</parameter> :</term>

1396

1342

<listitem><simpara> location to store an error of type <link linkend="GConvertError"><type>GConvertError</type></link>

1397

1343

</simpara></listitem></varlistentry>

1398

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="G-IO-STATUS-NORMAL:CAPS"><literal>G_IO_STATUS_NORMAL</literal></link> if the encoding was successfully set.

1344

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="G-IO-STATUS-NORMAL--CAPS"><literal>G_IO_STATUS_NORMAL</literal></link> if the encoding was successfully set.

1399

1345

</simpara></listitem></varlistentry>

1400

1346

</variablelist></refsect2>

1401

1402

<title><anchor id="g-io-channel-get-close-on-unref" role="function"/>g_io_channel_get_close_on_unref ()</title>

1403

<indexterm><primary>g_io_channel_get_close_on_unref</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_io_channel_get_close_on_unref (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>

1347

1348

<title>g_io_channel_get_close_on_unref ()</title>

1349

<indexterm zone="g-io-channel-get-close-on-unref"><primary sortas="g_io_channel_get_close_on_unref">g_io_channel_get_close_on_unref</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_io_channel_get_close_on_unref (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>

1404

1350

<para>

1405

1351

Returns whether the file/socket/whatever associated with <parameter>channel</parameter>

1406

1352

will be closed when <parameter>channel</parameter> receives its final unref and is

1407

destroyed. The default value of this is <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> for channels created

1408

by <link linkend="g-io-channel-new-file"><function>g_io_channel_new_file()</function></link>, and <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> for all other channels.</para>

1353

destroyed. The default value of this is <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> for channels created

1354

by <link linkend="g-io-channel-new-file"><function>g_io_channel_new_file()</function></link>, and <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> for all other channels.</para>

1409

1355

<para>

1410

1411

1356

</para><variablelist role="params">

1412

<varlistentry><term><parameter>channel</parameter> :</term>

1357

<varlistentry><term><parameter>channel</parameter> :</term>

1413

1358

<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>.

1414

1359

</simpara></listitem></varlistentry>

1415

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> Whether the channel will be closed on the final unref of

1360

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> Whether the channel will be closed on the final unref of

1416

1361

the GIOChannel data structure.

1417

1362

</simpara></listitem></varlistentry>

1418

1363

</variablelist></refsect2>

1419

1420

<title><anchor id="g-io-channel-set-close-on-unref" role="function"/>g_io_channel_set_close_on_unref ()</title>

1421

<indexterm><primary>g_io_channel_set_close_on_unref</primary></indexterm><programlisting><link linkend="void">void</link> g_io_channel_set_close_on_unref (<link linkend="GIOChannel">GIOChannel</link> *channel,

1364

1365

<title>g_io_channel_set_close_on_unref ()</title>

1366

<indexterm zone="g-io-channel-set-close-on-unref"><primary sortas="g_io_channel_set_close_on_unref">g_io_channel_set_close_on_unref</primary></indexterm><programlisting><link linkend="void">void</link> g_io_channel_set_close_on_unref (<link linkend="GIOChannel">GIOChannel</link> *channel,

1422

1367

1423

1368

<para>

1424

Setting this flag to <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> for a channel you have already closed

1369

Setting this flag to <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> for a channel you have already closed

1425

1370

can cause problems.</para>

1426

1371

<para>

1427

1428

1372

</para><variablelist role="params">

1429

<varlistentry><term><parameter>channel</parameter> :</term>

1373

<varlistentry><term><parameter>channel</parameter> :</term>

1430

1374

<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>

1431

1375

</simpara></listitem></varlistentry>

1432

<varlistentry><term><parameter>do_close</parameter> :</term>

1376

<varlistentry><term><parameter>do_close</parameter> :</term>

1433

1377

<listitem><simpara> Whether to close the channel on the final unref of

1434

1378

the GIOChannel data structure. The default value of

1435

this is <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> for channels created by <link linkend="g-io-channel-new-file"><function>g_io_channel_new_file()</function></link>,

1436

and <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> for all other channels.

1379

this is <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> for channels created by <link linkend="g-io-channel-new-file"><function>g_io_channel_new_file()</function></link>,

1380

and <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> for all other channels.

1437

1381

</simpara></listitem></varlistentry>

1438

1382

</variablelist></refsect2>

1439

1440

<title><anchor id="g-io-channel-read" role="function" condition="deprecated:2.2: Use g_io_channel_read_chars() instead."/>g_io_channel_read ()</title>

1441

<indexterm role="deprecated"><primary>g_io_channel_read</primary></indexterm><programlisting><link linkend="GIOError">GIOError</link> g_io_channel_read (<link linkend="GIOChannel">GIOChannel</link> *channel,

1383

1384

<title>g_io_channel_read ()</title>

1385

<indexterm zone="g-io-channel-read" role="deprecated"><primary sortas="g_io_channel_read">g_io_channel_read</primary></indexterm><programlisting><link linkend="GIOError">GIOError</link> g_io_channel_read (<link linkend="GIOChannel">GIOChannel</link> *channel,

1442

1386

1443

1387

1444

1388

1447

1391

Reads data from a <link linkend="GIOChannel"><type>GIOChannel</type></link>.</para>

1448

1392

<para>

1449

1393

</para><variablelist role="params">

1450

<varlistentry><term><parameter>channel</parameter> :</term>

1394

<varlistentry><term><parameter>channel</parameter> :</term>

1451

1395

<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>

1452

1396

</simpara></listitem></varlistentry>

1453

1397

1454

1398

<listitem><simpara> a buffer to read the data into (which should be at least

1455

1399

count bytes long)

1456

1400

</simpara></listitem></varlistentry>

1457

<varlistentry><term><parameter>count</parameter> :</term>

1401

<varlistentry><term><parameter>count</parameter> :</term>

1458

1402

<listitem><simpara> the number of bytes to read from the <link linkend="GIOChannel"><type>GIOChannel</type></link>

1459

1403

</simpara></listitem></varlistentry>

1460

<varlistentry><term><parameter>bytes_read</parameter> :</term>

1404

<varlistentry><term><parameter>bytes_read</parameter> :</term>

1461

1405

<listitem><simpara> returns the number of bytes actually read

1462

1406

</simpara></listitem></varlistentry>

1463

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="G-IO-ERROR-NONE:CAPS"><literal>G_IO_ERROR_NONE</literal></link> if the operation was successful.

1407

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="G-IO-ERROR-NONE--CAPS"><literal>G_IO_ERROR_NONE</literal></link> if the operation was successful.

1464

1408

1465

1409

</simpara></listitem></varlistentry>

1466

1410

</variablelist></refsect2>

1467

1468

<title><anchor id="GIOError" role="enum"/>enum GIOError</title>

1469

<indexterm><primary>GIOError</primary></indexterm><programlisting>typedef enum

1411

1412

<title>enum GIOError</title>

1413

<indexterm zone="GIOError"><primary sortas="GIOError">GIOError</primary></indexterm><programlisting>typedef enum

1470

1414

{

1471

1415

G_IO_ERROR_NONE,

1472

1416

G_IO_ERROR_AGAIN,

1478

1422

1479

1423

1480

1424

</para><variablelist role="enum">

1481

1482

<term><anchor id="G-IO-ERROR-NONE:CAPS" role="constant"/><literal>G_IO_ERROR_NONE</literal></term>

1425

1426

<term><literal>G_IO_ERROR_NONE</literal></term>

1483

1427

<listitem><simpara>no error

1484

1428

</simpara></listitem>

1485

1429

</varlistentry>

1486

1487

<term><anchor id="G-IO-ERROR-AGAIN:CAPS" role="constant"/><literal>G_IO_ERROR_AGAIN</literal></term>

1430

1431

<term><literal>G_IO_ERROR_AGAIN</literal></term>

1488

1432

<listitem><simpara>an EAGAIN error occurred

1489

1433

</simpara></listitem>

1490

1434

</varlistentry>

1491

1492

<term><anchor id="G-IO-ERROR-INVAL:CAPS" role="constant"/><literal>G_IO_ERROR_INVAL</literal></term>

1435

1436

<term><literal>G_IO_ERROR_INVAL</literal></term>

1493

1437

<listitem><simpara>an EINVAL error occurred

1494

1438

</simpara></listitem>

1495

1439

</varlistentry>

1496

1497

<term><anchor id="G-IO-ERROR-UNKNOWN:CAPS" role="constant"/><literal>G_IO_ERROR_UNKNOWN</literal></term>

1440

1441

<term><literal>G_IO_ERROR_UNKNOWN</literal></term>

1498

1442

<listitem><simpara>another error occurred

1499

1500

1443

</simpara></listitem>

1501

1444

</varlistentry>

1502

1445

</variablelist></refsect2>

1503

1504

<title><anchor id="g-io-channel-write" role="function" condition="deprecated:2.2: Use g_io_channel_write_chars() instead."/>g_io_channel_write ()</title>

1505

<indexterm role="deprecated"><primary>g_io_channel_write</primary></indexterm><programlisting><link linkend="GIOError">GIOError</link> g_io_channel_write (<link linkend="GIOChannel">GIOChannel</link> *channel,

1446

1447

<title>g_io_channel_write ()</title>

1448

<indexterm zone="g-io-channel-write" role="deprecated"><primary sortas="g_io_channel_write">g_io_channel_write</primary></indexterm><programlisting><link linkend="GIOError">GIOError</link> g_io_channel_write (<link linkend="GIOChannel">GIOChannel</link> *channel,

1506

1449

const <link linkend="gchar">gchar</link> *buf,

1507

1450

1508

1451

1511

1454

Writes data to a <link linkend="GIOChannel"><type>GIOChannel</type></link>.</para>

1512

1455

<para>

1513

1456

</para><variablelist role="params">

1514

<varlistentry><term><parameter>channel</parameter> :</term>

1457

<varlistentry><term><parameter>channel</parameter> :</term>

1515

1458

<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>

1516

1459

</simpara></listitem></varlistentry>

1517

1460

1518

1461

<listitem><simpara> the buffer containing the data to write

1519

1462

</simpara></listitem></varlistentry>

1520

<varlistentry><term><parameter>count</parameter> :</term>

1463

<varlistentry><term><parameter>count</parameter> :</term>

1521

1464

<listitem><simpara> the number of bytes to write

1522

1465

</simpara></listitem></varlistentry>

1523

<varlistentry><term><parameter>bytes_written</parameter> :</term>

1466

<varlistentry><term><parameter>bytes_written</parameter> :</term>

1524

1467

<listitem><simpara> the number of bytes actually written

1525

1468

</simpara></listitem></varlistentry>

1526

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="G-IO-ERROR-NONE:CAPS"><literal>G_IO_ERROR_NONE</literal></link> if the operation was successful.

1469

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="G-IO-ERROR-NONE--CAPS"><literal>G_IO_ERROR_NONE</literal></link> if the operation was successful.

1527

1470

1528

1471

</simpara></listitem></varlistentry>

1529

1472

</variablelist></refsect2>

1530

1531

<title><anchor id="g-io-channel-seek" role="function" condition="deprecated:2.2: Use g_io_channel_seek_position() instead."/>g_io_channel_seek ()</title>

1532

<indexterm role="deprecated"><primary>g_io_channel_seek</primary></indexterm><programlisting><link linkend="GIOError">GIOError</link> g_io_channel_seek (<link linkend="GIOChannel">GIOChannel</link> *channel,

1473

1474

<title>g_io_channel_seek ()</title>

1475

<indexterm zone="g-io-channel-seek" role="deprecated"><primary sortas="g_io_channel_seek">g_io_channel_seek</primary></indexterm><programlisting><link linkend="GIOError">GIOError</link> g_io_channel_seek (<link linkend="GIOChannel">GIOChannel</link> *channel,

1533

1476

1534

1477

1535

1478

<warning><para><literal>g_io_channel_seek</literal> has been deprecated since version 2.2 and should not be used in newly-written code. Use <link linkend="g-io-channel-seek-position"><function>g_io_channel_seek_position()</function></link> instead.</para></warning>

1538

1481

library function <link linkend="fseek"><function>fseek()</function></link>.</para>

1539

1482

<para>

1540

1483

</para><variablelist role="params">

1541

<varlistentry><term><parameter>channel</parameter> :</term>

1484

<varlistentry><term><parameter>channel</parameter> :</term>

1542

1485

<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>

1543

1486

</simpara></listitem></varlistentry>

1544

<varlistentry><term><parameter>offset</parameter> :</term>

1487

<varlistentry><term><parameter>offset</parameter> :</term>

1545

1488

<listitem><simpara> an offset, in bytes, which is added to the position specified

1546

1489

by <parameter>type</parameter>

1547

1490

</simpara></listitem></varlistentry>

1548

1549

<listitem><simpara> the position in the file, which can be <link linkend="G-SEEK-CUR:CAPS"><literal>G_SEEK_CUR</literal></link> (the current

1550

position), <link linkend="G-SEEK-SET:CAPS"><literal>G_SEEK_SET</literal></link> (the start of the file), or <link linkend="G-SEEK-END:CAPS"><literal>G_SEEK_END</literal></link>

1491

1492

<listitem><simpara> the position in the file, which can be <link linkend="G-SEEK-CUR--CAPS"><literal>G_SEEK_CUR</literal></link> (the current

1493

position), <link linkend="G-SEEK-SET--CAPS"><literal>G_SEEK_SET</literal></link> (the start of the file), or <link linkend="G-SEEK-END--CAPS"><literal>G_SEEK_END</literal></link>

1551

1494

(the end of the file)

1552

1495

</simpara></listitem></varlistentry>

1553

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="G-IO-ERROR-NONE:CAPS"><literal>G_IO_ERROR_NONE</literal></link> if the operation was successful.

1496

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="G-IO-ERROR-NONE--CAPS"><literal>G_IO_ERROR_NONE</literal></link> if the operation was successful.

1554

1497

1555

1498

</simpara></listitem></varlistentry>

1556

1499

</variablelist></refsect2>

1557

1558

<title><anchor id="g-io-channel-close" role="function" condition="deprecated:2.2: Use g_io_channel_shutdown() instead."/>g_io_channel_close ()</title>

1559

<indexterm role="deprecated"><primary>g_io_channel_close</primary></indexterm><programlisting><link linkend="void">void</link> g_io_channel_close (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>

1500

1501

<title>g_io_channel_close ()</title>

1502

<indexterm zone="g-io-channel-close" role="deprecated"><primary sortas="g_io_channel_close">g_io_channel_close</primary></indexterm><programlisting><link linkend="void">void</link> g_io_channel_close (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>

1560

1503

<warning><para><literal>g_io_channel_close</literal> has been deprecated since version 2.2 and should not be used in newly-written code. Use <link linkend="g-io-channel-shutdown"><function>g_io_channel_shutdown()</function></link> instead.</para></warning>

1561

1504

<para>

1562

1505

Close an IO channel. Any pending data to be written will be

1564

1507

last reference is dropped using <link linkend="g-io-channel-unref"><function>g_io_channel_unref()</function></link>.</para>

1565

1508

<para>

1566

1509

</para><variablelist role="params">

1567

<varlistentry><term><parameter>channel</parameter> :</term>

1510

<varlistentry><term><parameter>channel</parameter> :</term>

1568

1511

<listitem><simpara> A <link linkend="GIOChannel"><type>GIOChannel</type></link>

1569

1512

</simpara></listitem></varlistentry>

1570

1513

</variablelist></refsect2>

1573

1516

1574

1517

1575

1518

1576

1519

1577

1520

1578

1521

<para>

1579

1522

1580

1581

1523

1582

1524

<term><link linkend="gtk-input-add-full"><function>gtk_input_add_full()</function></link>, <link linkend="gtk-input-remove"><function>gtk_input_remove()</function></link>, <link linkend="gdk-input-add"><function>gdk_input_add()</function></link>,

1583

1525

1586

1528

1587

1529

</para></listitem>

1588

1530

</varlistentry>

1589

1590

1531

</variablelist>

1591

1532

</para>

1592

1533

</refsect1>

1593

1534

1594

1595

1596

1535

</refentry>

Older »