/* 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 #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: mach_msg_type_number_t); /* 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, dealloc; offset: off_t; amount: mach_msg_type_number_t); /* 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: mach_msg_type_number_t); /* 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 rendezvous2: mach_port_send_t); /* 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);