/* 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 #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 memobjxx: mach_port_send_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 are USER_NOT_IT and want to become it should call this function. The server will endeavor to have USER_IT when this returns, but users should call io_get_it in a loop for safety. */ /* INTR */ routine io_get_it ( io_object: io_t; cntl: memory_object_t); /* When the user become it, the user is USER_IT. When the user is done with the shared page, the filesystem may have changed the it status to USER_RELEASE_IT. In that case, rather than downgrading USER_IT to USER_POTENTIALLY_IT, the user should call io_release_it. 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_it. */ routine io_release_it ( io_object: io_t; cntl: memory_object_t); /* This routine should be called while the user is it, 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 it status is USER_IT or USER_RELEASE_IT. The user will keep it upon return. */ routine io_eofnotify ( io_object: io_t; cntl: memory_object_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 it status is USER_IT or USER_RELEASE_IT. The user will keep it upon return. */ routine io_prenotify ( io_object: io_t; cntl: memory_object_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 it status is USER_IT or USER_RELEASE_IT. The user will keep it upon return. */ routine io_postnotify ( io_object: io_t; cntl: memory_object_t; write_start: int; write_end: int); /* This routine sleeps until the read_size is increased. The it status should be USER_IT or USER_RELEASE_IT, and will be upon return. Any of the shared variables might change across this call. */ /* INTR */ routine io_readsleep ( io_object: io_t; cntl: memory_object_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; cntl: memory_object_t);