fdopen man page on DigitalUNIX

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
DigitalUNIX logo
[printable version]

fopen(3)							      fopen(3)

NAME
       fopen, freopen, fdopen - Open a stream

SYNOPSIS
       #include <stdio.h>

       FILE *fopen(
	       const char *path,
	       const char *mode ); FILE *fdopen(
	       int filedes,
	       const char *mode ); FILE *freopen(
	       const char *path,
	       const char *mode,
	       FILE *stream );

LIBRARY
       Standard C Library (libc)

STANDARDS
       Interfaces  documented on this reference page conform to industry stan‐
       dards as follows:

       fopen(), freopen():  ISO C, XSH4.0, XSH4.2, XSH5.0

       fdopen():  XSH4.0, XSH4.2, XSH5.0

       Refer to the standards(5) reference page	 for  more  information	 about
       industry standards and associated tags.

PARAMETERS
       Points  to  a character string that contains the name of the file to be
       opened.	If the final component of the path parameter specifies a  sym‐
       bolic  link,  the  link is traversed and pathname resolution continues.
       Points to a character string that controls whether the file  is	opened
       for  reading (r), writing (w), or appending (a) and whether the file is
       opened for updating (+). The mode can also include a b  parameter,  but
       this is ignored (see DESCRIPTION).  Specifies the input stream.	Speci‐
       fies a valid open file descriptor.

DESCRIPTION
       The fopen() function opens the file named by the path parameter and as‐
       sociates a stream with it, returning a pointer to the FILE structure of
       this stream.

       The mode parameter controls the	access	allowed	 to  the  stream.  The
       parameter can have one of the following values. In this list of values,
       the b character indicates a binary file.	 UNIX systems do  not  distin‐
       guish between binary and text files in the context of opening a stream,
       and the b character is therefore ignored.  However, the b character  is
       included	 in  X/Open standards for alignment with ISO C syntax that can
       apply to other kinds of operating systems.  Opens the file for reading.
       Creates	a  new file for writing, or opens and truncates a file to zero
       length.	(The file is  not  truncated  under  the  fdopen()  function.)
       Appends	(opens a file for writing at the end of the file, or creates a
       file for writing).  Opens a file	 for  update  (reading	and  writing).
       Truncates to zero length or creates a file for update. (The file is not
       truncated under the fdopen() function.)	 Appends  (opens  a  file  for
       update, writing at the end of the file, or creates a file for writing).

       When  you open a file for update, you can perform both input and output
       operations on the resulting stream. However, an output operation cannot
       be  directly followed by an input operation without an intervening call
       to the fflush() function	 or  a	file-positioning  operation  (fseek(),
       fsetpos(),  or  rewind()	 function). Also, an input operation cannot be
       directly followed by an output operation without an  intervening	 flush
       or  file	 positioning  operation, unless the input operation encounters
       the end of the file.

       When you open a file for append (that is, when the mode parameter is  a
       or  a+), it is impossible to overwrite information already in the file.
       You can use the fseek() function to reposition the file pointer to  any
       position	 in the file, but when output is written to the file, the cur‐
       rent file pointer is ignored. All output is written at the end  of  the
       file and the file pointer is repositioned to the end of the output.

       [Tru64  UNIX]  If two separate processes open the same file for append,
       each process can write freely to the file without destroying the output
       being written by the other. The output from the two processes is inter‐
       mixed in the order in which it is written to the file. Note that if the
       data is buffered, it is not actually written until it is flushed.

       When opened, a stream is fully buffered if and only if it can be deter‐
       mined that it does not refer to an interactive device.  The  error  and
       End-of-File indicators for the stream are cleared.

       If  the	mode  parameter is w, a, w+, or a+ and the file did not previ‐
       ously exist, upon successful completion the fopen() function marks  the
       st_atime, st_ctime and st_mtime fields of the file and the st_ctime and
       st_mtime fields of the parent directory for update. If the mode parame‐
       ter  is w or w+ and the file did previously exist, upon successful com‐
       pletion the fopen() function marks the st_ctime and st_mtime fields  of
       the file for update.

       The  freopen() function substitutes the named file in place of the open
       stream.	The original stream is closed regardless of whether the open()
       function	 succeeds with the named file.	The freopen() function returns
       a pointer to the FILE structure associated with the  stream  parameter.
       The  freopen()  function	 is  typically	used  to  attach the preopened
       streams associated with stdin, stdout, and stderr to other  files.  The
       function	 uses  the  mode  argument  in	the  same way as described for
       fopen().

       The fdopen() function  associates  a  stream  with  a  file  descriptor
       obtained	 from  an  open(),  dup(), creat(), or pipe() function.	 These
       functions open files, but do not return pointers	 to  FILE  structures.
       Many  of	 the  standard	I/O package functions require pointers to FILE
       structures. Note that the mode of the stream specified must agree  with
       the  mode  of  the open file. The meaning of mode values is the same as
       described for fopen(), except that for fdopen(), the  values  beginning
       with w do not cause truncation of the file.

       The  fdopen() function sets the file position indicator associated with
       the new stream to the position indicated by the file offset  associated
       with  the  file descriptor. The function also clears the error and End-
       of-File indicators for the stream.

   Stream Orientation
       [ISO C]	The current version of	the  ISO  C  standard  specifies  that
       streams	have an orientation: unbounded immediately after the stream is
       opened, byte oriented if operated on by a byte-oriented	I/O  function,
       and  wide-character  oriented  if  operated  on by a wide-character I/O
       function.  Furthermore, the standard defines the fwide()	 function  for
       explicitly  querying  stream  orientation and, if preceded by a call to
       freopen(), for changing stream orientation without  actually  operating
       on  the	stream	(see fwide(3)). The reasons for these additions to the
       standard are as follows.	 Both I/O functions that are byte oriented and
       those  that  are	 wide-character	 oriented  can	refer to the same FILE
       object.	For wide-character functions, the FILE object  is  assumed  to
       include	an  mb_state object to keep track of conversion-state informa‐
       tion that currently applies to the  stream.   Wide-character  functions
       are  designed with the assumption that they always begin execution with
       the stream positioned at the boundary between two multibyte characters.
       The  conversion-state  information in the mb_state object is needed for
       correct positioning when an application executes in a locale that  sup‐
       ports  shift-state  encoding.  While wide-character functions can main‐
       tain consistency between the conversion state and the stream, byte-ori‐
       ented  functions cannot. Therefore, a wide-character function cannot be
       assured of correct boundary positioning in an open stream if that  same
       stream  is  also operated on by a byte-oriented function. The additions
       to the ISO C standard allow application developers a way to  make  sure
       that  a	stream	opened by another function has the correct orientation
       (either unbounded or wide-character) before its associated FILE	object
       is referred to by a wide-character function.

RESTRICTIONS
       Currently,  Tru64  UNIX	systems	 do  not  provide locales that support
       shift-state  encoding.  Therefore,  the	ISO C  rules  and  definitions
       related	to shift-state encoding and stream orientation have no practi‐
       cal use when applications run on Tru64 UNIX  systems.   However,	 these
       rules  and definitions are included for your convenience in using Tru64
       UNIX to develop applications that run on multiple  platforms,  some  of
       which may support locales with shift-state encoding.

RETURN VALUES
       On  successful  completion,  the fopen(), fdopen(), and freopen() func‐
       tions return a pointer to the FILE object controlling the stream.

       If these functions fail, they return a null pointer and	set  errno  to
       indicate the error.

ERRORS
       The  fopen(), fdopen(), and freopen() functions set errno to the speci‐
       fied values for the following conditions:

       Search permission is denied on a component of the pathname  prefix;  or
       the file exists and the permissions specified by the mode parameter are
       denied; or the file does not exist and write permission is  denied  for
       the  parent directory of the file to be created (fopen() or freopen()).
       The filedes parameter is not a valid file descriptor  (fdopen()	only).
       The  function  (fopen()	or freopen()) was interrupted by a signal that
       was caught.  The mode parameter is not a valid mode.  The named file is
       a directory and mode requires write access (fopen() or freopen()).  Too
       many  links  were  encountered  in  translating	path.	OPEN_MAX  file
       descriptors are currently open in the calling process (freopen()).

	      [Tru64  UNIX]  Either the OPEN_MAX value or the per-process soft
	      descriptor limit is checked.

	      The FOPEN_MAX or STREAM_MAX streams are currently	 open  in  the
	      calling  process	(fopen() or fdopen()).	The length of the path
	      string exceeds PATH_MAX or a pathname component is  longer  than
	      NAME_MAX	(fopen()  or freopen()).  Too many files are currently
	      open in the system (fopen() or freopen()).  The named file  does
	      not  exist  or  the  path	 parameter  points  to an empty string
	      (fopen() or freopen()).  There is insufficient space to allocate
	      a	 buffer.   The directory or file system that would contain the
	      new file cannot be expanded (fopen() or freopen()).  A component
	      of  the  pathname	 prefix	 is  not  a directory (fopen() or fre‐
	      open()).	The named file is a character-special or block-special
	      file  and	 the device associated with this special file does not
	      exist (fopen() or freopen()).  [Tru64 UNIX]  The named file is a
	      socket  bound to the file system (a UNIX domain socket) and can‐
	      not be opened.  The named file resides on a read-only file  sys‐
	      tem  and mode requires write access (fopen() or freopen()).  The
	      file is being  executed  and  the	 mode  requires	 write	access
	      (fopen() or freopen()).

SEE ALSO
       Functions:  open(2),  fclose(3),	 fseek(3), fwide(3), setbuf(3), setlo‐
       cale(3)

       Standards: standards(5)

       Network Programmer's Guide

								      fopen(3)
[top]

List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net