path: root/hurd/io.defs

/* Definitions for generic IO interface
   Copyright (C) 1991, 1993 Free Software Foundation

This file is part of the GNU Hurd.

The GNU Hurd is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.

The GNU Hurd is distributed in the hope that it will be useful, 
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with the GNU Hurd; see the file COPYING.  If not, write to
the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.  */

subsystem io 21000;

#include <hurd/hurd_types.defs>

#ifdef IO_IMPORTS
IO_IMPORTS
#endif

/* Write data to an IO object.  If offset is -1, write at the object
   maintained file pointer.  If the object is not seekable, offset is
   ignored.  The amount successfully written is returned in amount.  */
/* INTR */
routine io_write (
	io_object: io_t;
	data: data_t;
	offset: off_t;
	out amount: int);

/* Read data from an IO object.  If offset if -1, read from the object
   maintained file pointer.  If the object is not seekable, offset is
   ignored.  The amount desired to be read is in amount.  */
/* INTR */
routine io_read (
	io_object: io_t;
	out data: data_t;
	offset: off_t;
	amount: int);

/* Change current read/write offset */
/* INTR */
routine io_seek (
	io_object: io_t;
	offset: off_t;
	whence: int;
	out newp: off_t);

/* Tell how much data can be read from the object without blocking for
   a "long time" (this should be the same meaning of "long time" used
   by the nonblocking flag.  */
routine io_readable (
	io_object: io_t;
	out amount: int);

/* This manipulates a descriptor flag (per open) controlling
   nonblocking mode.  If this flag is set, all further requests that
   might block for a "long time" will return EWOULDBLOCK instead.  */
routine io_mod_nonblock (
	io_object: io_t;
	on_or_off: int);

routine io_get_nonblock (
	io_object: io_t;
	out on_or_off: int);

/* This manipulates a descriptor flag (per open) controlling append
   mode.  If this flag is set, all further calls to io_write with an
   offset of -1 will append to the IO object, and move the file
   pointer accordingly.  The append_mode flag in the shared page
   structure is a copy of this flag.  This flag is meaningful only for
   seekable objects.  */
routine io_mod_append (
	io_object: io_t;
	on_or_off: int);

routine io_get_append (
	io_object: io_t;
	out on_or_off: int);

/* This requests that the IO object send SIGIO and SIGURG signals,
   when appropriate, to the designated port using sig_post.  A
   port is also returned which will be used as the reference port in
   sending such signals (this is the "async IO ID" port).  The async
   call is cancelled by deleting all refernces to the async_id_port.
   Each call to io_async generates a new ASYNC_ID_PORT.
   */
routine io_async (
	io_object: io_t;
	notify_port: mach_port_t;
	out async_id_port: mach_port_t);

/* Get/set the owner of the IO object.  For terminals, this affects
   controlling terminal behavior (see term_become_ctty).  For all
   objects this affects old-style async IO.  Negative values represent
   pgrps.  This has nothing to do with the owner of a file (as
   returned by io_stat, and as used for various permission checks by
   filesystems).  An owner of 0 indicates that there is no owner.  */
routine io_mod_owner (
	io_object: io_t;
	owner: pid_t);

routine io_get_owner (
	io_object: io_t;
	out owner: pid_t);

/* This provides "old style" async IO.  This is deprecated, and
   provided only for backward compatibility with 4.3 BSD.  This
   manipulates a per-object (not per-open) flag controlling old-style
   async mode.  If the bit is on, then the IO object will send SIGIO
   ande SIGURG signals (in precisely the same circumstances as
   io_async) to the current owner (pid or pgrp) as set by io_set_own.
   The reference port for the signal sends is the async_id_port
   returned by this call; it is up to the caller to communicate this
   to potential recipients of the signal.  (Such communication needs
   to be done both by the caller of the call and the caller of
   io_set_owner, in order to get the BSD functionality.)  One
   async_id_port is shared by all users of io_mod_async_icky and
   io_get_icky_async_id.  If on_or_off is 0, then the current
   old-style async port is deleted.  */
routine io_mod_async_icky (
	io_object: io_t;
	on_or_off: int;
	out icky_async_id_port: mach_port_t);

/* Fetch the current old-style async ID port.  */
routine io_get_icky_async_id (
	io_object: io_t;
	out icky_async_id_port: mach_port_t);

routine io_get_async_icky (
	io_object: io_t;
	out on_or_off: int);

/* Return the open status of the IO object.  This is a set of bits
   including FS_LOOKUP_READ, _WRITE, and _EXEC.  */
routine io_get_openstat (
	io_object: io_t;
	out open_stat: int);

/* Select_type is the or of SELECT_READ, SELECT_WRITE, and SELECT_URG.
   If any of the requested types of IO are immediately possible, the
   appropriate types are set in SELECT_RESULT, and RETURN_PORT is
   destroyed.  If IO is not immediately possible, SELECT_RESULT is
   zero, and a select_done call (see misc.defs) will be sent to
   RETURN_PORT when IO becomes possible.  RETURN_PORT should be a
   send-once right.  */
routine io_select (
	io_object: io_t;
	select_type: int;
	return_port: mach_port_make_send_once_t;
	id_tag: int;
	out select_result: int);

/* Return the current status of the object.  Not all the fields of the
   io_statuf_t are meaningful for all objects; however, the access and
   modify times, the optimal IO size, and the fs type are meaningful
   for all objects.  */
/* INTR */
routine io_stat (
	stat_object: io_t;
	out stat_info: io_statbuf_t);

/* Get a reauthenticated port to an io object.  The user should follow
   this with a call to auth_user_authenticate.  The new_port passed
   through the auth server will be a port usable with the new
   authentication.  */
simpleroutine io_reauthenticate (
	auth_object: io_t;
	rend_int: int);

/* Return another port which has been restricted to do only those
   things which both the current user and the newly specified user can
   do.  */
routine io_restrict_auth (
	io_object: io_t;
	out new_object: mach_port_send_t;
	uids: idarray_t;
	gids: idarray_t);

/* Return a new port with the same semantics as the existing port. */
routine io_duplicate (
	io_object: io_t;
	out newport: mach_port_send_t);

/* Get version information about the server exporting the IO object.  */
routine io_server_version (
	vers_object: io_t;
	out server_name: string_t;
	out server_major_version: int;
	out server_minor_version: int;
	out server_edit_level: int);

/* Definitions for mapped io */

/* Return object mapping the data underlying this memory object.  If
   the read-data and the write-data are the same (as for files)
   memobjxx will be set and both memobjrd and memobjwt will be
   MACH_PORT_NULL.  If the read-object and the write-object are
   distinct (as for TCP streams) memobjxx is MACH_PORT_NULL and the
   either or both of memobjrd and memobjwr will be set.  If memobjxx
   is returned, the the memory object will be readable, and writable
   iff the object is O_RDWR or O_WRONLY.  If memobjxx is not returned,
   memobjrd will be returned if the object is O_RDWR or O_RDONLY, and
   will not be writable; memobjwr will be returned if the object is
   O_RDWR or O_WRONLY, and will be readable and writable.  Some
   objects do not provide mapping; they will set none of the ports and
   return an error.  Such objects can still be accessed by io_read and
   io_write.  */
routine io_map (
	io_object: io_t;
	out memobjrd: mach_port_send_t;
	out memobjwt: mach_port_send_t);

/* This call can only be made once per request port.  If it returns
   POSIX_EBUSY, then the user should duplicate the port (using
   io_duplicate) and try again.  This maps the shared page data
   structures corresponding to the data maps in io_map.  The format
   and meaning of the shared page is described in shared.h and the
   calls below.  */
routine io_map_cntl (
	io_object: io_t;
	out memobj: memory_object_t);

/* Users of the shared page who don't have the conch and want it
   should call this function.  The server will endeavor to have
   USER_HAS_CONCH when this returns, but users should call io_get_it
   in a loop for safety.  */
/* INTR */
routine io_get_conch (
	io_object: io_t);

/* When the user is done with the shared page, while holding the
   conch, the filesystem may have changed the conch status to
   USER_RELEASE_CONCH.  In that case, rather than downgrading
   USER_HAS_CONCH to USER_COULD_HAVE_CONCH, the user should call
   io_release_conch.  Also, when the user is done with an IO object
   and wants permanent characteristics of the object (like file size)
   to be updated, the user should call io_release_conch.  Upon return,
   the conch status might be either USER_COULD_HAVE_CONCH or
   USER_HAS_NOT_CONCH. */
routine io_release_conch (
	io_object: io_t);

/* This routine should be called while the user has the conch, after
   the user has encountered an eof condition (where the file pointer
   is equal to the file size).  This could be used by terminals, for
   example, to clear the eof condition after it is read once.  The
   routine should be called while the user has the conch. The user
   will keep it upon return.  */
routine io_eofnotify (
	io_object: io_t);

/* If the user wants to write past the prenotify size, a call needs to
   be made to io_prenotify giving the paramters of the write.  Upon
   return from io_prenotify, there is no guarantee that the prenotify
   size will now permit the write, so it should be re-checked.  The
   routine should be called while the user has the conch.  The user
   will keep it upon return.  */
routine io_prenotify (
	io_object: io_t;
	write_start: int;
	write_end: int);

/* After doing a write which extends past the postnotify_size, the
   user needs to call io_postnotify.  The routine should be called
   while the user has the conch.  The user will keep it upon return.
   */
routine io_postnotify (
	io_object: io_t;
	write_start: int;
	write_end: int);

/* This routine sleeps until the read_size is increased.  The routine
   should be called while the user has the conch.  The user will keep
   it upon return.  */
/* INTR */
routine io_readsleep (
	io_object: io_t);
   
/* The shared user has just done some IO, and a signal needs to be
   sent for async users.  */
routine io_sigio (
	io_object: io_t);