Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
pack_fopen_chunk(3)		Allegro	manual		   pack_fopen_chunk(3)

NAME
       pack_fopen_chunk	 -  Opens a sub-chunk of a file. Allegro game program-
       ming library.

SYNOPSIS
       #include	<allegro.h>

       PACKFILE	*pack_fopen_chunk(PACKFILE *f, int pack);

DESCRIPTION
       Opens a sub-chunk of a file. Chunks are primarily intended for  use  by
       the  datafile  code, but	they may also be useful	for your own file rou-
       tines. A	chunk provides a logical view of part of a file, which can  be
       compressed  as  an  individual entity and will automatically insert and
       check length counts to prevent reading past the end of the  chunk.  The
       PACKFILE	parameter is a previously opened file, and `pack' is a boolean
       parameter which will turn compression on	for the	 sub-chunk  if	it  is
       non-zero.  Example:

	  PACKFILE *output = pack_fopen("out.raw", "w!");
	  ...
	  /* Create a sub-chunk	with compression. */
	  output = pack_fopen_chunk(output, 1);
	  if (!output)
	     abort_on_error("Error saving data!");
	  /* Write some	data to	the sub-chunk. */
	  ...
	  /* Close the sub-chunk, recovering parent file. */
	  output = pack_fclose_chunk(output);

       The  data  written to the chunk will be prefixed	with two length	counts
       (32-bit,	a.k.a. big-endian). For	uncompressed chunks these will both be
       set  to	the size of the	data in	the chunk. For compressed chunks (cre-
       ated by setting the `pack' flag), the first length will be the raw size
       of  the	chunk,	and the	second will be the negative size of the	uncom-
       pressed data.

       To read the chunk, use the following code:

	  PACKFILE *input = pack_fopen("out.raw", "rp");
	  ...
	  input	= pack_fopen_chunk(input, 1);
	  /* Read data from the	sub-chunk and close it.	*/
	  ...
	  input	= pack_fclose_chunk(input);

       This sequence will read the length counts created when  the  chunk  was
       written,	 and  automatically decompress the contents of the chunk if it
       was compressed. The length will also be used to	prevent	 reading  past
       the end of the chunk (Allegro will return EOF if	you attempt this), and
       to automatically	 skip  past  any  unread  chunk	 data  when  you  call
       pack_fclose_chunk().

       Chunks  can  be	nested	inside	each other by making repeated calls to
       pack_fopen_chunk(). When	writing	a file,	the compression	status is  in-
       herited	from the parent	file, so you only need to set the pack flag if
       the parent is not compressed but	you want to pack the  chunk  data.  If
       the  parent  file is already open in packed mode, setting the pack flag
       will result in data being compressed twice: once	as it  is  written  to
       the chunk, and again as the chunk passes	it on to the parent file.

RETURN VALUE
       Returns	a  pointer  to	the sub-chunked	PACKFILE, or NULL if there was
       some error (eg. you are using a custom PACKFILE vtable).

SEE ALSO
       pack_fclose_chunk(3), pack_fopen(3)

Allegro				 version 4.4.2		   pack_fopen_chunk(3)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pack_fopen_chunk&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help