path: root/hurd/io.defs

/* Definitions for generic IO interface
   Copyright (C) 1991, 1993, 1994 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.  */


/* All changes to this file must be reflected in io_request.defs and
   io_reply.defs. */

subsystem io 21000;

#include <hurd/hurd_types.defs>

#ifdef IO_IMPORTS
IO_IMPORTS
#endif

INTR_INTERFACE


/* 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.  A
   given user should not have more than one outstanding io_write on an
   object at a time; servers implement congestion control by delaying
   responses to io_write.  Servers may drop data (returning ENOBUFS)
   if they recevie more than one write when not prepared for it.  */
routine io_write (
	io_object: io_t;
	RPT
	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.  */
routine io_read (
	io_object: io_t;
	RPT
	out data: data_t;
	offset: off_t;
	amount: int);

/* Change current read/write offset */
routine io_seek (
	io_object: io_t;
	RPT
	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;
	RPT
	out amount: int);

/* These four routines modify the O_APPEND, O_ASYNC, O_FSYNC, and
   O_NONBLOCK bits for the IO object. In addition, io_get_openmodes
   will tell you which of O_READ, O_WRITE, and O_EXEC the object can
   be used for.  The O_ASYNC bit affects icky async I/O; good async 
   I/O is done through io_async which is orthogonal to these calls. */
routine io_set_all_openmodes (
	io_object: io_t;
	RPT
	newbits: int);

routine io_get_openmodes (
	io_object: io_t;
	RPT
	out bits: int);

routine io_set_some_openmodes (
	io_object: io_t;
	RPT
	bits_to_set: int);

routine io_clear_some_openmodes (
	io_object: io_t;
	RPT
	bits_to_clear: 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;
	RPT
	notify_port: mach_port_send_t;
	out async_id_port: mach_port_send_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;
	RPT
	owner: pid_t);

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

/* This provides "old style" async IO.  This is deprecated, and
   provided only for backward compatibility with 4.3 BSD.  This
   implements a per-object (not per-open) flag controlling old-style
   async mode (O_ASYNC).  If the flag is set, then the IO object will
   send SIGIO and 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
   icky_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_mod_owner, in order to get the BSD functionality.)
   One async_id_port is shared by all users of io_get_icky_async_id. */
/* Fetch the current old-style async ID port.  */
routine io_get_icky_async_id (
	io_object: io_t;
	RPT
	out icky_async_id_port: mach_port_send_t);

/* 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 an io_select_done call (see msg.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;
	RPT
	select_type: int;
	return_port: mach_port_poly_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.  */
routine io_stat (
	stat_object: io_t;
	RPT
	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;
	RPT
	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;
	RPT
	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;
	RPT
	out newport: mach_port_send_t);

/* Get version information about the server exporting the IO object.  */
routine io_server_version (
	vers_object: io_t;
	RPT
	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 objects mapping the data underlying this memory object.  If
   the object can be read then memobjrd will be provided; if the
   object can be written then memobjwr will be provided.  For objects
   where read data and write data are the same, these objects will be
   equal, otherwise they will be disjoint.  Servers are permitted to
   implement io_map but not io_map_cntl.  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;
	RPT
	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
   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.
   This call may be unimplemented by some servers; they will return
   EOPNOTSUPP.
   */
routine io_map_cntl (
	io_object: io_t;
	RPT
	out memobj: mach_port_send_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.  */
routine io_get_conch (
	io_object: io_t RPTLAST);

/* 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 RPTLAST);

/* 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 RPTLAST);

/* 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;
	RPT
	write_start: vm_offset_t;
	write_end: vm_offset_t);

/* 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;
	RPT
	write_start: vm_offset_t;
	write_end: vm_offset_t);

/* After moving rd_file_pointer past readnotify_size, the user should
   call this routine, while holding the conch.  The user will keep the
   conch upon return. */
routine io_readnotify (
	io_object: io_t RPTLAST);

/* 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.  */
routine io_readsleep (
	io_object: io_t RPTLAST);
   
/* 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 RPTLAST);