1UnixLabels(3) OCaml library UnixLabels(3)
2
6 UnixLabels - Interface to the Unix system.
7
9 Module UnixLabels
10
12 Module UnixLabels
13 : sig end
14 Interface to the Unix system. To use as replacement to default Unix
17 module, add module Unix = UnixLabels in your implementation.
18 Error report
26 type error = Unix.error =
27 | E2BIG (* Argument list too long
28 *)
29 | EACCES (* Permission denied
30 *)
31 | EAGAIN (* Resource temporarily unavailable; try again
32 *)
33 | EBADF (* Bad file descriptor
34 *)
35 | EBUSY (* Resource unavailable
36 *)
37 | ECHILD (* No child process
38 *)
39 | EDEADLK (* Resource deadlock would occur
40 *)
41 | EDOM (* Domain error for math functions, etc.
42 *)
43 | EEXIST (* File exists
44 *)
45 | EFAULT (* Bad address
46 *)
47 | EFBIG (* File too large
48 *)
49 | EINTR (* Function interrupted by signal
50 *)
51 | EINVAL (* Invalid argument
52 *)
53 | EIO (* Hardware I/O error
54 *)
55 | EISDIR (* Is a directory
56 *)
57 | EMFILE (* Too many open files by the process
58 *)
59 | EMLINK (* Too many links
60 *)
61 | ENAMETOOLONG (* Filename too long
62 *)
63 | ENFILE (* Too many open files in the system
64 *)
65 | ENODEV (* No such device
66 *)
67 | ENOENT (* No such file or directory
68 *)
69 | ENOEXEC (* Not an executable file
70 *)
71 | ENOLCK (* No locks available
72 *)
73 | ENOMEM (* Not enough memory
74 *)
75 | ENOSPC (* No space left on device
76 *)
77 | ENOSYS (* Function not supported
78 *)
79 | ENOTDIR (* Not a directory
80 *)
81 | ENOTEMPTY (* Directory not empty
82 *)
83 | ENOTTY (* Inappropriate I/O control operation
84 *)
85 | ENXIO (* No such device or address
86 *)
87 | EPERM (* Operation not permitted
88 *)
89 | EPIPE (* Broken pipe
90 *)
91 | ERANGE (* Result too large
92 *)
93 | EROFS (* Read-only file system
94 *)
95 | ESPIPE (* Invalid seek e.g. on a pipe
96 *)
97 | ESRCH (* No such process
98 *)
99 | EXDEV (* Invalid link
100 *)
101 | EWOULDBLOCK (* Operation would block
102 *)
103 | EINPROGRESS (* Operation now in progress
104 *)
105 | EALREADY (* Operation already in progress
106 *)
107 | ENOTSOCK (* Socket operation on non-socket
108 *)
109 | EDESTADDRREQ (* Destination address required
110 *)
111 | EMSGSIZE (* Message too long
112 *)
113 | EPROTOTYPE (* Protocol wrong type for socket
114 *)
115 | ENOPROTOOPT (* Protocol not available
116 *)
117 | EPROTONOSUPPORT (* Protocol not supported
118 *)
119 | ESOCKTNOSUPPORT (* Socket type not supported
120 *)
121 | EOPNOTSUPP (* Operation not supported on socket
122 *)
123 | EPFNOSUPPORT (* Protocol family not supported
124 *)
125 | EAFNOSUPPORT (* Address family not supported by protocol family
126 *)
127 | EADDRINUSE (* Address already in use
128 *)
129 | EADDRNOTAVAIL (* Can't assign requested address
130 *)
131 | ENETDOWN (* Network is down
132 *)
133 | ENETUNREACH (* Network is unreachable
134 *)
135 | ENETRESET (* Network dropped connection on reset
136 *)
137 | ECONNABORTED (* Software caused connection abort
138 *)
139 | ECONNRESET (* Connection reset by peer
140 *)
141 | ENOBUFS (* No buffer space available
142 *)
143 | EISCONN (* Socket is already connected
144 *)
145 | ENOTCONN (* Socket is not connected
146 *)
147 | ESHUTDOWN (* Can't send after socket shutdown
148 *)
149 | ETOOMANYREFS (* Too many references: can't splice
150 *)
151 | ETIMEDOUT (* Connection timed out
152 *)
153 | ECONNREFUSED (* Connection refused
154 *)
155 | EHOSTDOWN (* Host is down
156 *)
157 | EHOSTUNREACH (* No route to host
158 *)
159 | ELOOP (* Too many levels of symbolic links
160 *)
161 | EOVERFLOW (* File size or position not representable
162 *)
163 | EUNKNOWNERR of int
164 (* Unknown error
165 *)
166 The type of error codes. Errors defined in the POSIX standard and ad‐
169 ditional errors from UNIX98 and BSD. All other errors are mapped to
170 EUNKNOWNERR.
171 exception Unix_error of error * string * string
175 Raised by the system calls below when an error is encountered. The
178 first component is the error code; the second component is the function
179 name; the third component is the string parameter to the function, if
180 it has one, or the empty string otherwise.
181 val error_message : error -> string
185 Return a string describing the given error code.
187 val handle_unix_error : ('a -> 'b) -> 'a -> 'b
191 handle_unix_error f x applies f to x and returns the result. If the
194 exception Unix_error is raised, it prints a message describing the er‐
195 ror and exits with code 2.
196 Access to the process environment
201 val environment : unit -> string array
202 Return the process environment, as an array of strings with the format
204 ``variable=value''.
205 val getenv : string -> string
209 Return the value associated to a variable in the process environment.
211 Raise Not_found if the variable is unbound. (This function is identi‐
212 cal to Sys.getenv .)
213 val unsafe_getenv : string -> string
217 Return the value associated to a variable in the process environment.
219 Unlike UnixLabels.getenv , this function returns the value even if the
221 process has special privileges. It is considered unsafe because the
222 programmer of a setuid or setgid program must be careful to avoid using
223 maliciously crafted environment variables in the search path for exe‐
224 cutables, the locations for temporary files or logs, and the like.
225 Since 4.06.0
228 Raises Not_found if the variable is unbound.
231 val putenv : string -> string -> unit
235 Unix.putenv name value sets the value associated to a variable in the
238 process environment. name is the name of the environment variable, and
239 value its new associated value.
240 Process handling
245 type process_status = Unix.process_status =
246 | WEXITED of int
247 (* The process terminated normally by exit ; the argument is the re‐
248 turn code.
249 *)
250 | WSIGNALED of int
251 (* The process was killed by a signal; the argument is the signal
252 number.
253 *)
254 | WSTOPPED of int
255 (* The process was stopped by a signal; the argument is the signal
256 number.
257 *)
258 The termination status of a process. See module Sys for the defini‐
261 tions of the standard signal numbers. Note that they are not the num‐
262 bers used by the OS.
263 type wait_flag = Unix.wait_flag =
266 | WNOHANG (* do not block if no child has died yet, but immediately
267 return with a pid equal to 0.
268 *)
269 | WUNTRACED (* report also the children that receive stop signals.
270 *)
271 Flags for UnixLabels.waitpid .
274 val execv : prog:string -> args:string array -> 'a
278 execv prog args execute the program in file prog , with the arguments
281 args , and the current process environment. These execv* functions
282 never return: on success, the current program is replaced by the new
283 one; on failure, a UnixLabels.Unix_error exception is raised.
284 val execve : prog:string -> args:string array -> env:string array -> 'a
288 Same as UnixLabels.execv , except that the third argument provides the
290 environment to the program executed.
291 val execvp : prog:string -> args:string array -> 'a
295 Same as UnixLabels.execv , except that the program is searched in the
297 path.
298 val execvpe : prog:string -> args:string array -> env:string array ->
302 'a
303 Same as UnixLabels.execve , except that the program is searched in the
305 path.
306 val fork : unit -> int
310 Fork a new process. The returned integer is 0 for the child process,
312 the pid of the child process for the parent process.
313 val wait : unit -> int * process_status
317 Wait until one of the children processes die, and return its pid and
319 termination status.
320 val waitpid : mode:wait_flag list -> int -> int * process_status
324 Same as UnixLabels.wait , but waits for the child process whose pid is
326 given. A pid of -1 means wait for any child. A pid of 0 means wait
327 for any child in the same process group as the current process. Nega‐
328 tive pid arguments represent process groups. The list of options indi‐
329 cates whether waitpid should return immediately without waiting, or
330 also report stopped children.
331 val system : string -> process_status
335 Execute the given command, wait until it terminates, and return its
337 termination status. The string is interpreted by the shell /bin/sh and
338 therefore can contain redirections, quotes, variables, etc. The result
339 WEXITED 127 indicates that the shell couldn't be executed.
340 val getpid : unit -> int
344 Return the pid of the process.
346 val getppid : unit -> int
350 Return the pid of the parent process.
352 val nice : int -> int
356 Change the process priority. The integer argument is added to the
358 ``nice'' value. (Higher values of the ``nice'' value mean lower priori‐
359 ties.) Return the new nice value.
360 Basic file input/output
365 type file_descr = Unix.file_descr
366 The abstract type of file descriptors.
369 val stdin : file_descr
373 File descriptor for standard input.
375 val stdout : file_descr
379 File descriptor for standard output.
381 val stderr : file_descr
385 File descriptor for standard error.
387 type open_flag = Unix.open_flag =
390 | O_RDONLY (* Open for reading
391 *)
392 | O_WRONLY (* Open for writing
393 *)
394 | O_RDWR (* Open for reading and writing
395 *)
396 | O_NONBLOCK (* Open in non-blocking mode
397 *)
398 | O_APPEND (* Open for append
399 *)
400 | O_CREAT (* Create if nonexistent
401 *)
402 | O_TRUNC (* Truncate to 0 length if existing
403 *)
404 | O_EXCL (* Fail if existing
405 *)
406 | O_NOCTTY (* Don't make this dev a controlling tty
407 *)
408 | O_DSYNC (* Writes complete as `Synchronised I/O data integrity com‐
409 pletion'
410 *)
411 | O_SYNC (* Writes complete as `Synchronised I/O file integrity com‐
412 pletion'
413 *)
414 | O_RSYNC (* Reads complete as writes (depending on O_SYNC/O_DSYNC)
415 *)
416 | O_SHARE_DELETE (* Windows only: allow the file to be deleted while
417 still open
418 *)
419 | O_CLOEXEC (* Set the close-on-exec flag on the descriptor returned
420 by UnixLabels.openfile
421 *)
423 | O_KEEPEXEC (* Clear the close-on-exec flag. This is currently the
424 default.
425 *)
426 The flags to UnixLabels.openfile .
429 type file_perm = int
432 The type of file access rights, e.g. 0o640 is read and write for user,
435 read for group, none for others
436 val openfile : string -> mode:open_flag list -> perm:file_perm ->
440 file_descr
441 Open the named file with the given flags. Third argument is the permis‐
443 sions to give to the file if it is created. Return a file descriptor on
444 the named file.
445 val close : file_descr -> unit
449 Close a file descriptor.
451 val read : file_descr -> buf:bytes -> pos:int -> len:int -> int
455 read fd buff ofs len reads len bytes from descriptor fd , storing them
458 in byte sequence buff , starting at position ofs in buff . Return the
459 number of bytes actually read.
460 val write : file_descr -> buf:bytes -> pos:int -> len:int -> int
464 write fd buff ofs len writes len bytes to descriptor fd , taking them
467 from byte sequence buff , starting at position ofs in buff . Return the
468 number of bytes actually written. write repeats the writing operation
469 until all bytes have been written or an error occurs.
470 val single_write : file_descr -> buf:bytes -> pos:int -> len:int -> int
474 Same as write , but attempts to write only once. Thus, if an error oc‐
476 curs, single_write guarantees that no data has been written.
477 val write_substring : file_descr -> buf:string -> pos:int -> len:int ->
481 int
482 Same as write , but take the data from a string instead of a byte se‐
484 quence.
485 Since 4.02.0
488 val single_write_substring : file_descr -> buf:string -> pos:int ->
492 len:int -> int
493 Same as single_write , but take the data from a string instead of a
495 byte sequence.
496 Since 4.02.0
499 Interfacing with the standard input/output library
504 val in_channel_of_descr : file_descr -> in_channel
505 Create an input channel reading from the given descriptor. The channel
507 is initially in binary mode; use set_binary_mode_in ic false if text
508 mode is desired.
509 val out_channel_of_descr : file_descr -> out_channel
513 Create an output channel writing on the given descriptor. The channel
515 is initially in binary mode; use set_binary_mode_out oc false if text
516 mode is desired.
517 val descr_of_in_channel : in_channel -> file_descr
521 Return the descriptor corresponding to an input channel.
523 val descr_of_out_channel : out_channel -> file_descr
527 Return the descriptor corresponding to an output channel.
529 Seeking and truncating
534 type seek_command = Unix.seek_command =
535 | SEEK_SET (* indicates positions relative to the beginning of the
536 file
537 *)
538 | SEEK_CUR (* indicates positions relative to the current position
539 *)
540 | SEEK_END (* indicates positions relative to the end of the file
541 *)
542 Positioning modes for UnixLabels.lseek .
545 val lseek : file_descr -> int -> mode:seek_command -> int
549 Set the current position for a file descriptor, and return the result‐
551 ing offset (from the beginning of the file).
552 val truncate : string -> len:int -> unit
556 Truncates the named file to the given size.
558 val ftruncate : file_descr -> len:int -> unit
562 Truncates the file corresponding to the given descriptor to the given
564 size.
565 File status
570 type file_kind = Unix.file_kind =
571 | S_REG (* Regular file
572 *)
573 | S_DIR (* Directory
574 *)
575 | S_CHR (* Character device
576 *)
577 | S_BLK (* Block device
578 *)
579 | S_LNK (* Symbolic link
580 *)
581 | S_FIFO (* Named pipe
582 *)
583 | S_SOCK (* Socket
584 *)
585 type stats = Unix.stats = {
590 st_dev : int ; (* Device number
591 *)
592 st_ino : int ; (* Inode number
593 *)
594 st_kind : file_kind ; (* Kind of the file
595 *)
596 st_perm : file_perm ; (* Access rights
597 *)
598 st_nlink : int ; (* Number of links
599 *)
600 st_uid : int ; (* User id of the owner
601 *)
602 st_gid : int ; (* Group ID of the file's group
603 *)
604 st_rdev : int ; (* Device ID (if special file)
605 *)
606 st_size : int ; (* Size in bytes
607 *)
608 st_atime : float ; (* Last access time
609 *)
610 st_mtime : float ; (* Last modification time
611 *)
612 st_ctime : float ; (* Last status change time
613 *)
614 }
615 The information returned by the UnixLabels.stat calls.
618 val stat : string -> stats
622 Return the information for the named file.
624 val lstat : string -> stats
628 Same as UnixLabels.stat , but in case the file is a symbolic link, re‐
630 turn the information for the link itself.
631 val fstat : file_descr -> stats
635 Return the information for the file associated with the given descrip‐
637 tor.
638 val isatty : file_descr -> bool
642 Return true if the given file descriptor refers to a terminal or con‐
644 sole window, false otherwise.
645 File operations on large files
650 module LargeFile : sig end
651 File operations on large files. This sub-module provides 64-bit vari‐
654 ants of the functions UnixLabels.lseek (for positioning a file descrip‐
655 tor), UnixLabels.truncate and UnixLabels.ftruncate (for changing the
656 size of a file), and UnixLabels.stat , UnixLabels.lstat and UnixLa‐
657 bels.fstat (for obtaining information on files). These alternate func‐
658 tions represent positions and sizes by 64-bit integers (type int64 )
659 instead of regular integers (type int ), thus allowing operating on
660 files whose sizes are greater than max_int .
661 Mapping files into memory
666 val map_file : file_descr -> ?pos:int64 -> kind:('a, 'b) Bigarray.kind
667 -> layout:'c Bigarray.layout -> shared:bool -> dims:int array -> ('a,
668 'b, 'c) Bigarray.Genarray.t
669 Memory mapping of a file as a Bigarray. map_file fd kind layout shared
671 dims returns a Bigarray of kind kind , layout layout , and dimensions
672 as specified in dims . The data contained in this Bigarray are the
673 contents of the file referred to by the file descriptor fd (as opened
674 previously with Unix.openfile , for example). The optional pos parame‐
675 ter is the byte offset in the file of the data being mapped; it de‐
676 faults to 0 (map from the beginning of the file).
677 If shared is true , all modifications performed on the array are re‐
679 flected in the file. This requires that fd be opened with write per‐
680 missions. If shared is false , modifications performed on the array
681 are done in memory only, using copy-on-write of the modified pages; the
682 underlying file is not affected.
683 Genarray.map_file is much more efficient than reading the whole file in
686 a Bigarray, modifying that Bigarray, and writing it afterwards.
687 To adjust automatically the dimensions of the Bigarray to the actual
689 size of the file, the major dimension (that is, the first dimension for
690 an array with C layout, and the last dimension for an array with For‐
691 tran layout) can be given as -1 . Genarray.map_file then determines
692 the major dimension from the size of the file. The file must contain
693 an integral number of sub-arrays as determined by the non-major dimen‐
694 sions, otherwise Failure is raised.
695 If all dimensions of the Bigarray are given, the file size is matched
697 against the size of the Bigarray. If the file is larger than the Bi‐
698 garray, only the initial portion of the file is mapped to the Bigarray.
699 If the file is smaller than the big array, the file is automatically
700 grown to the size of the Bigarray. This requires write permissions on
701 fd .
702 Array accesses are bounds-checked, but the bounds are determined by the
704 initial call to map_file . Therefore, you should make sure no other
705 process modifies the mapped file while you're accessing it, or a SIGBUS
706 signal may be raised. This happens, for instance, if the file is
707 shrunk.
708 Invalid_argument or Failure may be raised in cases where argument vali‐
711 dation fails.
712 Since 4.06.0
715 Operations on file names
720 val unlink : string -> unit
721 Removes the named file
723 val rename : src:string -> dst:string -> unit
727 rename old new changes the name of a file from old to new .
730 val link : ?follow:bool -> src:string -> dst:string -> unit
734 link ?follow source dest creates a hard link named dest to the file
737 named source .
738 Raises ENOSYS On Unix if ~follow:_ is requested, but linkat is unavail‐
741 able.
742 Raises ENOSYS On Windows if ~follow:false is requested.
745 File permissions and ownership
750 type access_permission = Unix.access_permission =
751 | R_OK (* Read permission
752 *)
753 | W_OK (* Write permission
754 *)
755 | X_OK (* Execution permission
756 *)
757 | F_OK (* File exists
758 *)
759 Flags for the UnixLabels.access call.
762 val chmod : string -> perm:file_perm -> unit
766 Change the permissions of the named file.
768 val fchmod : file_descr -> perm:file_perm -> unit
772 Change the permissions of an opened file.
774 val chown : string -> uid:int -> gid:int -> unit
778 Change the owner uid and owner gid of the named file.
780 val fchown : file_descr -> uid:int -> gid:int -> unit
784 Change the owner uid and owner gid of an opened file.
786 val umask : int -> int
790 Set the process's file mode creation mask, and return the previous
792 mask.
793 val access : string -> perm:access_permission list -> unit
797 Check that the process has the given permissions over the named file.
799 Raise Unix_error otherwise.
800 Operations on file descriptors
805 val dup : ?cloexec:bool -> file_descr -> file_descr
806 Return a new file descriptor referencing the same file as the given de‐
808 scriptor.
809 val dup2 : ?cloexec:bool -> src:file_descr -> dst:file_descr -> unit
813 dup2 fd1 fd2 duplicates fd1 to fd2 , closing fd2 if already opened.
816 val set_nonblock : file_descr -> unit
820 Set the ``non-blocking'' flag on the given descriptor. When the
822 non-blocking flag is set, reading on a descriptor on which there is
823 temporarily no data available raises the EAGAIN or EWOULDBLOCK error
824 instead of blocking; writing on a descriptor on which there is tempo‐
825 rarily no room for writing also raises EAGAIN or EWOULDBLOCK .
826 val clear_nonblock : file_descr -> unit
830 Clear the ``non-blocking'' flag on the given descriptor. See UnixLa‐
832 bels.set_nonblock .
833 val set_close_on_exec : file_descr -> unit
837 Set the ``close-on-exec'' flag on the given descriptor. A descriptor
839 with the close-on-exec flag is automatically closed when the current
840 process starts another program with one of the exec functions.
841 val clear_close_on_exec : file_descr -> unit
845 Clear the ``close-on-exec'' flag on the given descriptor. See UnixLa‐
847 bels.set_close_on_exec .
848 Directories
853 val mkdir : string -> perm:file_perm -> unit
854 Create a directory with the given permissions.
856 val rmdir : string -> unit
860 Remove an empty directory.
862 val chdir : string -> unit
866 Change the process working directory.
868 val getcwd : unit -> string
872 Return the name of the current working directory.
874 val chroot : string -> unit
878 Change the process root directory.
880 type dir_handle = Unix.dir_handle
883 The type of descriptors over opened directories.
886 val opendir : string -> dir_handle
890 Open a descriptor on a directory
892 val readdir : dir_handle -> string
896 Return the next entry in a directory.
898 Raises End_of_file when the end of the directory has been reached.
901 val rewinddir : dir_handle -> unit
905 Reposition the descriptor to the beginning of the directory
907 val closedir : dir_handle -> unit
911 Close a directory descriptor.
913 Pipes and redirections
918 val pipe : ?cloexec:bool -> unit -> file_descr * file_descr
919 Create a pipe. The first component of the result is opened for reading,
921 that's the exit to the pipe. The second component is opened for writ‐
922 ing, that's the entrance to the pipe.
923 val mkfifo : string -> perm:file_perm -> unit
927 Create a named pipe with the given permissions.
929 High-level process and redirection management
934 val create_process : prog:string -> args:string array -> stdin:file_de‐
935 scr -> stdout:file_descr -> stderr:file_descr -> int
936 create_process prog args new_stdin new_stdout new_stderr forks a new
939 process that executes the program in file prog , with arguments args .
940 The pid of the new process is returned immediately; the new process ex‐
941 ecutes concurrently with the current process. The standard input and
942 outputs of the new process are connected to the descriptors new_stdin ,
943 new_stdout and new_stderr . Passing e.g. stdout for new_stdout pre‐
944 vents the redirection and causes the new process to have the same stan‐
945 dard output as the current process. The executable file prog is
946 searched in the path. The new process has the same environment as the
947 current process.
948 val create_process_env : prog:string -> args:string array -> env:string
952 array -> stdin:file_descr -> stdout:file_descr -> stderr:file_descr ->
953 int
954 create_process_env prog args env new_stdin new_stdout new_stderr works
957 as UnixLabels.create_process , except that the extra argument env spec‐
958 ifies the environment passed to the program.
959 val open_process_in : string -> in_channel
963 High-level pipe and process management. This function runs the given
965 command in parallel with the program. The standard output of the com‐
966 mand is redirected to a pipe, which can be read via the returned input
967 channel. The command is interpreted by the shell /bin/sh (cf. system
968 ).
969 val open_process_out : string -> out_channel
973 Same as UnixLabels.open_process_in , but redirect the standard input of
975 the command to a pipe. Data written to the returned output channel is
976 sent to the standard input of the command. Warning: writes on output
977 channels are buffered, hence be careful to call flush at the right
978 times to ensure correct synchronization.
979 val open_process : string -> in_channel * out_channel
983 Same as UnixLabels.open_process_out , but redirects both the standard
985 input and standard output of the command to pipes connected to the two
986 returned channels. The input channel is connected to the output of the
987 command, and the output channel to the input of the command.
988 val open_process_full : string -> env:string array -> in_channel *
992 out_channel * in_channel
993 Similar to UnixLabels.open_process , but the second argument specifies
995 the environment passed to the command. The result is a triple of chan‐
996 nels connected respectively to the standard output, standard input, and
997 standard error of the command.
998 val open_process_args_in : string -> string array -> in_channel
1002 High-level pipe and process management. The first argument specifies
1004 the command to run, and the second argument specifies the argument ar‐
1005 ray passed to the command. This function runs the command in parallel
1006 with the program. The standard output of the command is redirected to
1007 a pipe, which can be read via the returned input channel.
1008 Since 4.08.0
1011 val open_process_args_out : string -> string array -> out_channel
1015 Same as Unix.open_process_args_in , but redirect the standard input of
1017 the command to a pipe. Data written to the returned output channel is
1018 sent to the standard input of the command. Warning: writes on output
1019 channels are buffered, hence be careful to call flush at the right
1020 times to ensure correct synchronization.
1021 Since 4.08.0
1024 val open_process_args : string -> string array -> in_channel *
1028 out_channel
1029 Same as Unix.open_process_args_out , but redirects both the standard
1031 input and standard output of the command to pipes connected to the two
1032 returned channels. The input channel is connected to the output of the
1033 command, and the output channel to the input of the command.
1034 Since 4.08.0
1037 val open_process_args_full : string -> string array -> string array ->
1041 in_channel * out_channel * in_channel
1042 Similar to Unix.open_process_args , but the third argument specifies
1044 the environment passed to the command. The result is a triple of chan‐
1045 nels connected respectively to the standard output, standard input, and
1046 standard error of the command.
1047 Since 4.08.0
1050 val close_process_in : in_channel -> process_status
1054 Close channels opened by UnixLabels.open_process_in , wait for the as‐
1056 sociated command to terminate, and return its termination status.
1057 val close_process_out : out_channel -> process_status
1061 Close channels opened by UnixLabels.open_process_out , wait for the as‐
1063 sociated command to terminate, and return its termination status.
1064 val close_process : in_channel * out_channel -> process_status
1068 Close channels opened by UnixLabels.open_process , wait for the associ‐
1070 ated command to terminate, and return its termination status.
1071 val close_process_full : in_channel * out_channel * in_channel ->
1075 process_status
1076 Close channels opened by UnixLabels.open_process_full , wait for the
1078 associated command to terminate, and return its termination status.
1079 Symbolic links
1084 val symlink : ?to_dir:bool -> src:string -> dst:string -> unit
1085 symlink source dest creates the file dest as a symbolic link to the
1088 file source . See Unix.symlink for details of ~to_dir
1089 val has_symlink : unit -> bool
1094 Returns true if the user is able to create symbolic links. On Windows,
1096 this indicates that the user not only has the SeCreateSymbolicLinkPriv‐
1097 ilege but is also running elevated, if necessary. On other platforms,
1098 this is simply indicates that the symlink system call is available.
1099 Since 4.03.0
1102 val readlink : string -> string
1106 Read the contents of a link.
1108 Polling
1113 val select : read:file_descr list -> write:file_descr list -> ex‐
1114 cept:file_descr list -> timeout:float -> file_descr list * file_descr
1115 list * file_descr list
1116 Wait until some input/output operations become possible on some chan‐
1118 nels. The three list arguments are, respectively, a set of descriptors
1119 to check for reading (first argument), for writing (second argument),
1120 or for exceptional conditions (third argument). The fourth argument is
1121 the maximal timeout, in seconds; a negative fourth argument means no
1122 timeout (unbounded wait). The result is composed of three sets of de‐
1123 scriptors: those ready for reading (first component), ready for writing
1124 (second component), and over which an exceptional condition is pending
1125 (third component).
1126 Locking
1131 type lock_command = Unix.lock_command =
1132 | F_ULOCK (* Unlock a region
1133 *)
1134 | F_LOCK (* Lock a region for writing, and block if already locked
1135 *)
1136 | F_TLOCK (* Lock a region for writing, or fail if already locked
1137 *)
1138 | F_TEST (* Test a region for other process locks
1139 *)
1140 | F_RLOCK (* Lock a region for reading, and block if already locked
1141 *)
1142 | F_TRLOCK (* Lock a region for reading, or fail if already locked
1143 *)
1144 Commands for UnixLabels.lockf .
1147 val lockf : file_descr -> mode:lock_command -> len:int -> unit
1151 lockf fd cmd size puts a lock on a region of the file opened as fd .
1154 The region starts at the current read/write position for fd (as set by
1155 UnixLabels.lseek ), and extends size bytes forward if size is positive,
1156 size bytes backwards if size is negative, or to the end of the file if
1157 size is zero. A write lock prevents any other process from acquiring a
1158 read or write lock on the region. A read lock prevents any other
1159 process from acquiring a write lock on the region, but lets other pro‐
1160 cesses acquire read locks on it.
1161 The F_LOCK and F_TLOCK commands attempts to put a write lock on the
1163 specified region. The F_RLOCK and F_TRLOCK commands attempts to put a
1164 read lock on the specified region. If one or several locks put by an‐
1165 other process prevent the current process from acquiring the lock,
1166 F_LOCK and F_RLOCK block until these locks are removed, while F_TLOCK
1167 and F_TRLOCK fail immediately with an exception. The F_ULOCK removes
1168 whatever locks the current process has on the specified region. Fi‐
1169 nally, the F_TEST command tests whether a write lock can be acquired on
1170 the specified region, without actually putting a lock. It returns im‐
1171 mediately if successful, or fails otherwise.
1172 Signals
1177 Note: installation of signal handlers is performed via the functions
1178 Sys.signal and Sys.set_signal .
1179 val kill : pid:int -> signal:int -> unit
1181 kill pid sig sends signal number sig to the process with id pid .
1184 type sigprocmask_command = Unix.sigprocmask_command =
1187 | SIG_SETMASK
1188 | SIG_BLOCK
1189 | SIG_UNBLOCK
1190 val sigprocmask : mode:sigprocmask_command -> int list -> int list
1196 sigprocmask cmd sigs changes the set of blocked signals. If cmd is
1199 SIG_SETMASK , blocked signals are set to those in the list sigs . If
1200 cmd is SIG_BLOCK , the signals in sigs are added to the set of blocked
1201 signals. If cmd is SIG_UNBLOCK , the signals in sigs are removed from
1202 the set of blocked signals. sigprocmask returns the set of previously
1203 blocked signals.
1204 val sigpending : unit -> int list
1208 Return the set of blocked signals that are currently pending.
1210 val sigsuspend : int list -> unit
1214 sigsuspend sigs atomically sets the blocked signals to sigs and waits
1217 for a non-ignored, non-blocked signal to be delivered. On return, the
1218 blocked signals are reset to their initial value.
1219 val pause : unit -> unit
1223 Wait until a non-ignored, non-blocked signal is delivered.
1225 Time functions
1230 type process_times = Unix.process_times = {
1231 tms_utime : float ; (* User time for the process
1232 *)
1233 tms_stime : float ; (* System time for the process
1234 *)
1235 tms_cutime : float ; (* User time for the children processes
1236 *)
1237 tms_cstime : float ; (* System time for the children processes
1238 *)
1239 }
1240 The execution times (CPU times) of a process.
1243 type tm = Unix.tm = {
1246 tm_sec : int ; (* Seconds 0..60
1247 *)
1248 tm_min : int ; (* Minutes 0..59
1249 *)
1250 tm_hour : int ; (* Hours 0..23
1251 *)
1252 tm_mday : int ; (* Day of month 1..31
1253 *)
1254 tm_mon : int ; (* Month of year 0..11
1255 *)
1256 tm_year : int ; (* Year - 1900
1257 *)
1258 tm_wday : int ; (* Day of week (Sunday is 0)
1259 *)
1260 tm_yday : int ; (* Day of year 0..365
1261 *)
1262 tm_isdst : bool ; (* Daylight time savings in effect
1263 *)
1264 }
1265 The type representing wallclock time and calendar date.
1268 val time : unit -> float
1272 Return the current time since 00:00:00 GMT, Jan. 1, 1970, in seconds.
1274 val gettimeofday : unit -> float
1278 Same as UnixLabels.time , but with resolution better than 1 second.
1280 val gmtime : float -> tm
1284 Convert a time in seconds, as returned by UnixLabels.time , into a date
1286 and a time. Assumes UTC (Coordinated Universal Time), also known as
1287 GMT.
1288 val localtime : float -> tm
1292 Convert a time in seconds, as returned by UnixLabels.time , into a date
1294 and a time. Assumes the local time zone.
1295 val mktime : tm -> float * tm
1299 Convert a date and time, specified by the tm argument, into a time in
1301 seconds, as returned by UnixLabels.time . The tm_isdst , tm_wday and
1302 tm_yday fields of tm are ignored. Also return a normalized copy of the
1303 given tm record, with the tm_wday , tm_yday , and tm_isdst fields re‐
1304 computed from the other fields, and the other fields normalized (so
1305 that, e.g., 40 October is changed into 9 November). The tm argument is
1306 interpreted in the local time zone.
1307 val alarm : int -> int
1311 Schedule a SIGALRM signal after the given number of seconds.
1313 val sleep : int -> unit
1317 Stop execution for the given number of seconds.
1319 val times : unit -> process_times
1323 Return the execution times of the process.
1325 val utimes : string -> access:float -> modif:float -> unit
1329 Set the last access time (second arg) and last modification time (third
1331 arg) for a file. Times are expressed in seconds from 00:00:00 GMT, Jan.
1332 1, 1970. A time of 0.0 is interpreted as the current time.
1333 type interval_timer = Unix.interval_timer =
1336 | ITIMER_REAL (* decrements in real time, and sends the signal
1337 SIGALRM when expired.
1338 *)
1339 | ITIMER_VIRTUAL (* decrements in process virtual time, and sends
1340 SIGVTALRM when expired.
1341 *)
1342 | ITIMER_PROF (* (for profiling) decrements both when the process is
1343 running and when the system is running on behalf of the process; it
1344 sends SIGPROF when expired.
1345 *)
1346 The three kinds of interval timers.
1349 type interval_timer_status = Unix.interval_timer_status = {
1352 it_interval : float ; (* Period
1353 *)
1354 it_value : float ; (* Current value of the timer
1355 *)
1356 }
1357 The type describing the status of an interval timer
1360 val getitimer : interval_timer -> interval_timer_status
1364 Return the current status of the given interval timer.
1366 val setitimer : interval_timer -> interval_timer_status -> inter‐
1370 val_timer_status
1371 setitimer t s sets the interval timer t and returns its previous sta‐
1374 tus. The s argument is interpreted as follows: s.it_value , if nonzero,
1375 is the time to the next timer expiration; s.it_interval , if nonzero,
1376 specifies a value to be used in reloading it_value when the timer ex‐
1377 pires. Setting s.it_value to zero disable the timer. Setting s.it_in‐
1378 terval to zero causes the timer to be disabled after its next expira‐
1379 tion.
1380 User id, group id
1385 val getuid : unit -> int
1386 Return the user id of the user executing the process.
1388 val geteuid : unit -> int
1392 Return the effective user id under which the process runs.
1394 val setuid : int -> unit
1398 Set the real user id and effective user id for the process.
1400 val getgid : unit -> int
1404 Return the group id of the user executing the process.
1406 val getegid : unit -> int
1410 Return the effective group id under which the process runs.
1412 val setgid : int -> unit
1416 Set the real group id and effective group id for the process.
1418 val getgroups : unit -> int array
1422 Return the list of groups to which the user executing the process be‐
1424 longs.
1425 val setgroups : int array -> unit
1429 setgroups groups sets the supplementary group IDs for the calling
1432 process. Appropriate privileges are required.
1433 val initgroups : string -> int -> unit
1437 initgroups user group initializes the group access list by reading the
1440 group database /etc/group and using all groups of which user is a mem‐
1441 ber. The additional group group is also added to the list.
1442 type passwd_entry = Unix.passwd_entry = {
1445 pw_name : string ;
1446 pw_passwd : string ;
1447 pw_uid : int ;
1448 pw_gid : int ;
1449 pw_gecos : string ;
1450 pw_dir : string ;
1451 pw_shell : string ;
1452 }
1453 Structure of entries in the passwd database.
1456 type group_entry = Unix.group_entry = {
1459 gr_name : string ;
1460 gr_passwd : string ;
1461 gr_gid : int ;
1462 gr_mem : string array ;
1463 }
1464 Structure of entries in the groups database.
1467 val getlogin : unit -> string
1471 Return the login name of the user executing the process.
1473 val getpwnam : string -> passwd_entry
1477 Find an entry in passwd with the given name, or raise Not_found if the
1479 matching entry is not found.
1480 val getgrnam : string -> group_entry
1484 Find an entry in group with the given name, or raise Not_found if the
1486 matching entry is not found.
1487 val getpwuid : int -> passwd_entry
1491 Find an entry in passwd with the given user id, or raise Not_found if
1493 the matching entry is not found.
1494 val getgrgid : int -> group_entry
1498 Find an entry in group with the given group id, or raise Not_found if
1500 the matching entry is not found.
1501 Internet addresses
1506 type inet_addr = Unix.inet_addr
1507 The abstract type of Internet addresses.
1510 val inet_addr_of_string : string -> inet_addr
1514 Conversion from the printable representation of an Internet address to
1516 its internal representation. The argument string consists of 4 numbers
1517 separated by periods ( XXX.YYY.ZZZ.TTT ) for IPv4 addresses, and up to
1518 8 numbers separated by colons for IPv6 addresses. Raise Failure when
1519 given a string that does not match these formats.
1520 val string_of_inet_addr : inet_addr -> string
1524 Return the printable representation of the given Internet address. See
1526 Unix.inet_addr_of_string for a description of the printable representa‐
1527 tion.
1528 val inet_addr_any : inet_addr
1532 A special IPv4 address, for use only with bind , representing all the
1534 Internet addresses that the host machine possesses.
1535 val inet_addr_loopback : inet_addr
1539 A special IPv4 address representing the host machine ( 127.0.0.1 ).
1541 val inet6_addr_any : inet_addr
1545 A special IPv6 address, for use only with bind , representing all the
1547 Internet addresses that the host machine possesses.
1548 val inet6_addr_loopback : inet_addr
1552 A special IPv6 address representing the host machine ( ::1 ).
1554 Sockets
1559 type socket_domain = Unix.socket_domain =
1560 | PF_UNIX (* Unix domain
1561 *)
1562 | PF_INET (* Internet domain (IPv4)
1563 *)
1564 | PF_INET6 (* Internet domain (IPv6)
1565 *)
1566 The type of socket domains. Not all platforms support IPv6 sockets
1569 (type PF_INET6 ).
1570 type socket_type = Unix.socket_type =
1573 | SOCK_STREAM (* Stream socket
1574 *)
1575 | SOCK_DGRAM (* Datagram socket
1576 *)
1577 | SOCK_RAW (* Raw socket
1578 *)
1579 | SOCK_SEQPACKET (* Sequenced packets socket
1580 *)
1581 The type of socket kinds, specifying the semantics of communications.
1584 type sockaddr = Unix.sockaddr =
1587 | ADDR_UNIX of string
1588 | ADDR_INET of inet_addr * int
1589 The type of socket addresses. ADDR_UNIX name is a socket address in
1592 the Unix domain; name is a file name in the file system.
1593 ADDR_INET(addr,port) is a socket address in the Internet domain; addr
1594 is the Internet address of the machine, and port is the port number.
1595 val socket : ?cloexec:bool -> domain:socket_domain -> kind:socket_type
1599 -> protocol:int -> file_descr
1600 Create a new socket in the given domain, and with the given kind. The
1602 third argument is the protocol type; 0 selects the default protocol for
1603 that kind of sockets.
1604 val domain_of_sockaddr : sockaddr -> socket_domain
1608 Return the socket domain adequate for the given socket address.
1610 val socketpair : ?cloexec:bool -> domain:socket_domain ->
1614 kind:socket_type -> protocol:int -> file_descr * file_descr
1615 Create a pair of unnamed sockets, connected together.
1617 val accept : ?cloexec:bool -> file_descr -> file_descr * sockaddr
1621 Accept connections on the given socket. The returned descriptor is a
1623 socket connected to the client; the returned address is the address of
1624 the connecting client.
1625 val bind : file_descr -> addr:sockaddr -> unit
1629 Bind a socket to an address.
1631 val connect : file_descr -> addr:sockaddr -> unit
1635 Connect a socket to an address.
1637 val listen : file_descr -> max:int -> unit
1641 Set up a socket for receiving connection requests. The integer argument
1643 is the maximal number of pending requests.
1644 type shutdown_command = Unix.shutdown_command =
1647 | SHUTDOWN_RECEIVE (* Close for receiving
1648 *)
1649 | SHUTDOWN_SEND (* Close for sending
1650 *)
1651 | SHUTDOWN_ALL (* Close both
1652 *)
1653 The type of commands for shutdown .
1656 val shutdown : file_descr -> mode:shutdown_command -> unit
1660 Shutdown a socket connection. SHUTDOWN_SEND as second argument causes
1662 reads on the other end of the connection to return an end-of-file con‐
1663 dition. SHUTDOWN_RECEIVE causes writes on the other end of the connec‐
1664 tion to return a closed pipe condition ( SIGPIPE signal).
1665 val getsockname : file_descr -> sockaddr
1669 Return the address of the given socket.
1671 val getpeername : file_descr -> sockaddr
1675 Return the address of the host connected to the given socket.
1677 type msg_flag = Unix.msg_flag =
1680 | MSG_OOB
1681 | MSG_DONTROUTE
1682 | MSG_PEEK
1683 The flags for UnixLabels.recv , UnixLabels.recvfrom , UnixLabels.send
1686 and UnixLabels.sendto .
1687 val recv : file_descr -> buf:bytes -> pos:int -> len:int ->
1691 mode:msg_flag list -> int
1692 Receive data from a connected socket.
1694 val recvfrom : file_descr -> buf:bytes -> pos:int -> len:int ->
1698 mode:msg_flag list -> int * sockaddr
1699 Receive data from an unconnected socket.
1701 val send : file_descr -> buf:bytes -> pos:int -> len:int ->
1705 mode:msg_flag list -> int
1706 Send data over a connected socket.
1708 val send_substring : file_descr -> buf:string -> pos:int -> len:int ->
1712 mode:msg_flag list -> int
1713 Same as send , but take the data from a string instead of a byte se‐
1715 quence.
1716 Since 4.02.0
1719 val sendto : file_descr -> buf:bytes -> pos:int -> len:int ->
1723 mode:msg_flag list -> addr:sockaddr -> int
1724 Send data over an unconnected socket.
1726 val sendto_substring : file_descr -> buf:string -> pos:int -> len:int
1730 -> mode:msg_flag list -> sockaddr -> int
1731 Same as sendto , but take the data from a string instead of a byte se‐
1733 quence.
1734 Since 4.02.0
1737 Socket options
1742 type socket_bool_option =
1743 | SO_DEBUG (* Record debugging information
1744 *)
1745 | SO_BROADCAST (* Permit sending of broadcast messages
1746 *)
1747 | SO_REUSEADDR (* Allow reuse of local addresses for bind
1748 *)
1749 | SO_KEEPALIVE (* Keep connection active
1750 *)
1751 | SO_DONTROUTE (* Bypass the standard routing algorithms
1752 *)
1753 | SO_OOBINLINE (* Leave out-of-band data in line
1754 *)
1755 | SO_ACCEPTCONN (* Report whether socket listening is enabled
1756 *)
1757 | TCP_NODELAY (* Control the Nagle algorithm for TCP sockets
1758 *)
1759 | IPV6_ONLY (* Forbid binding an IPv6 socket to an IPv4 address
1760 *)
1761 The socket options that can be consulted with UnixLabels.getsockopt and
1764 modified with UnixLabels.setsockopt . These options have a boolean (
1765 true / false ) value.
1766 type socket_int_option =
1769 | SO_SNDBUF (* Size of send buffer
1770 *)
1771 | SO_RCVBUF (* Size of received buffer
1772 *)
1773 | SO_ERROR (* Deprecated. Use Unix.getsockopt_error instead.
1774 *)
1775 | SO_TYPE (* Report the socket type
1776 *)
1777 | SO_RCVLOWAT (* Minimum number of bytes to process for input opera‐
1778 tions
1779 *)
1780 | SO_SNDLOWAT (* Minimum number of bytes to process for output opera‐
1781 tions
1782 *)
1783 The socket options that can be consulted with UnixLabels.getsockopt_int
1786 and modified with UnixLabels.setsockopt_int . These options have an
1787 integer value.
1788 type socket_optint_option =
1791 | SO_LINGER (* Whether to linger on closed connections that have data
1792 present, and for how long (in seconds)
1793 *)
1794 The socket options that can be consulted with Unix.getsockopt_optint
1797 and modified with Unix.setsockopt_optint . These options have a value
1798 of type int option , with None meaning ``disabled''.
1799 type socket_float_option =
1802 | SO_RCVTIMEO (* Timeout for input operations
1803 *)
1804 | SO_SNDTIMEO (* Timeout for output operations
1805 *)
1806 The socket options that can be consulted with UnixLabels.getsock‐
1809 opt_float and modified with UnixLabels.setsockopt_float . These op‐
1810 tions have a floating-point value representing a time in seconds. The
1811 value 0 means infinite timeout.
1812 val getsockopt : file_descr -> socket_bool_option -> bool
1816 Return the current status of a boolean-valued option in the given
1818 socket.
1819 val setsockopt : file_descr -> socket_bool_option -> bool -> unit
1823 Set or clear a boolean-valued option in the given socket.
1825 val getsockopt_int : file_descr -> socket_int_option -> int
1829 Same as Unix.getsockopt for an integer-valued socket option.
1831 val setsockopt_int : file_descr -> socket_int_option -> int -> unit
1835 Same as Unix.setsockopt for an integer-valued socket option.
1837 val getsockopt_optint : file_descr -> socket_optint_option -> int op‐
1841 tion
1842 Same as Unix.getsockopt for a socket option whose value is an int op‐
1844 tion .
1845 val setsockopt_optint : file_descr -> socket_optint_option -> int op‐
1849 tion -> unit
1850 Same as Unix.setsockopt for a socket option whose value is an int op‐
1852 tion .
1853 val getsockopt_float : file_descr -> socket_float_option -> float
1857 Same as Unix.getsockopt for a socket option whose value is a float‐
1859 ing-point number.
1860 val setsockopt_float : file_descr -> socket_float_option -> float ->
1864 unit
1865 Same as Unix.setsockopt for a socket option whose value is a float‐
1867 ing-point number.
1868 val getsockopt_error : file_descr -> error option
1872 Return the error condition associated with the given socket, and clear
1874 it.
1875 High-level network connection functions
1880 val open_connection : sockaddr -> in_channel * out_channel
1881 Connect to a server at the given address. Return a pair of buffered
1883 channels connected to the server. Remember to call flush on the output
1884 channel at the right times to ensure correct synchronization.
1885 val shutdown_connection : in_channel -> unit
1889 ``Shut down'' a connection established with UnixLabels.open_connection
1891 ; that is, transmit an end-of-file condition to the server reading on
1892 the other side of the connection.
1893 val establish_server : (in_channel -> out_channel -> unit) ->
1897 addr:sockaddr -> unit
1898 Establish a server on the given address. The function given as first
1900 argument is called for each connection with two buffered channels con‐
1901 nected to the client. A new process is created for each connection. The
1902 function UnixLabels.establish_server never returns normally.
1903 Host and protocol databases
1908 type host_entry = Unix.host_entry = {
1909 h_name : string ;
1910 h_aliases : string array ;
1911 h_addrtype : socket_domain ;
1912 h_addr_list : inet_addr array ;
1913 }
1914 Structure of entries in the hosts database.
1917 type protocol_entry = Unix.protocol_entry = {
1920 p_name : string ;
1921 p_aliases : string array ;
1922 p_proto : int ;
1923 }
1924 Structure of entries in the protocols database.
1927 type service_entry = Unix.service_entry = {
1930 s_name : string ;
1931 s_aliases : string array ;
1932 s_port : int ;
1933 s_proto : string ;
1934 }
1935 Structure of entries in the services database.
1938 val gethostname : unit -> string
1942 Return the name of the local host.
1944 val gethostbyname : string -> host_entry
1948 Find an entry in hosts with the given name, or raise Not_found .
1950 val gethostbyaddr : inet_addr -> host_entry
1954 Find an entry in hosts with the given address, or raise Not_found .
1956 val getprotobyname : string -> protocol_entry
1960 Find an entry in protocols with the given name, or raise Not_found .
1962 val getprotobynumber : int -> protocol_entry
1966 Find an entry in protocols with the given protocol number, or raise
1968 Not_found .
1969 val getservbyname : string -> protocol:string -> service_entry
1973 Find an entry in services with the given name, or raise Not_found .
1975 val getservbyport : int -> protocol:string -> service_entry
1979 Find an entry in services with the given service number, or raise
1981 Not_found .
1982 type addr_info = {
1985 ai_family : socket_domain ; (* Socket domain
1986 *)
1987 ai_socktype : socket_type ; (* Socket type
1988 *)
1989 ai_protocol : int ; (* Socket protocol number
1990 *)
1991 ai_addr : sockaddr ; (* Address
1992 *)
1993 ai_canonname : string ; (* Canonical host name
1994 *)
1995 }
1996 Address information returned by Unix.getaddrinfo .
1999 type getaddrinfo_option =
2002 | AI_FAMILY of socket_domain
2003 (* Impose the given socket domain
2004 *)
2005 | AI_SOCKTYPE of socket_type
2006 (* Impose the given socket type
2007 *)
2008 | AI_PROTOCOL of int
2009 (* Impose the given protocol
2010 *)
2011 | AI_NUMERICHOST (* Do not call name resolver, expect numeric IP ad‐
2012 dress
2013 *)
2014 | AI_CANONNAME (* Fill the ai_canonname field of the result
2015 *)
2016 | AI_PASSIVE (* Set address to ``any'' address for use with Unix.bind
2017 *)
2019 Options to Unix.getaddrinfo .
2022 val getaddrinfo : string -> string -> getaddrinfo_option list ->
2026 addr_info list
2027 getaddrinfo host service opts returns a list of Unix.addr_info records
2030 describing socket parameters and addresses suitable for communicating
2031 with the given host and service. The empty list is returned if the
2032 host or service names are unknown, or the constraints expressed in opts
2033 cannot be satisfied.
2034 host is either a host name or the string representation of an IP ad‐
2037 dress. host can be given as the empty string; in this case, the
2038 ``any'' address or the ``loopback'' address are used, depending whether
2039 opts contains AI_PASSIVE . service is either a service name or the
2040 string representation of a port number. service can be given as the
2041 empty string; in this case, the port field of the returned addresses is
2042 set to 0. opts is a possibly empty list of options that allows the
2043 caller to force a particular socket domain (e.g. IPv6 only or IPv4
2044 only) or a particular socket type (e.g. TCP only or UDP only).
2045 type name_info = {
2048 ni_hostname : string ; (* Name or IP address of host
2049 *)
2050 ni_service : string ; (* Name of service or port number
2051 *)
2052 }
2053 Host and service information returned by Unix.getnameinfo .
2056 type getnameinfo_option =
2059 | NI_NOFQDN (* Do not qualify local host names
2060 *)
2061 | NI_NUMERICHOST (* Always return host as IP address
2062 *)
2063 | NI_NAMEREQD (* Fail if host name cannot be determined
2064 *)
2065 | NI_NUMERICSERV (* Always return service as port number
2066 *)
2067 | NI_DGRAM (* Consider the service as UDP-based instead of the de‐
2068 fault TCP
2069 *)
2070 Options to Unix.getnameinfo .
2073 val getnameinfo : sockaddr -> getnameinfo_option list -> name_info
2077 getnameinfo addr opts returns the host name and service name corre‐
2080 sponding to the socket address addr . opts is a possibly empty list of
2081 options that governs how these names are obtained. Raise Not_found if
2082 an error occurs.
2083 Terminal interface
2088 The following functions implement the POSIX standard terminal inter‐
2089 face. They provide control over asynchronous communication ports and
2090 pseudo-terminals. Refer to the termios man page for a complete descrip‐
2091 tion.
2092 type terminal_io = Unix.terminal_io = {
2094 mutable c_ignbrk : bool ; (* Ignore the break condition.
2096 *)
2097 mutable c_brkint : bool ; (* Signal interrupt on break condition.
2099 *)
2100 mutable c_ignpar : bool ; (* Ignore characters with parity errors.
2102 *)
2103 mutable c_parmrk : bool ; (* Mark parity errors.
2105 *)
2106 mutable c_inpck : bool ; (* Enable parity check on input.
2108 *)
2109 mutable c_istrip : bool ; (* Strip 8th bit on input characters.
2111 *)
2112 mutable c_inlcr : bool ; (* Map NL to CR on input.
2114 *)
2115 mutable c_igncr : bool ; (* Ignore CR on input.
2117 *)
2118 mutable c_icrnl : bool ; (* Map CR to NL on input.
2120 *)
2121 mutable c_ixon : bool ; (* Recognize XON/XOFF characters on input.
2123 *)
2124 mutable c_ixoff : bool ; (* Emit XON/XOFF chars to control input flow.
2126 *)
2127 mutable c_opost : bool ; (* Enable output processing.
2129 *)
2130 mutable c_obaud : int ; (* Output baud rate (0 means close connec‐
2132 tion).
2133 *)
2134 mutable c_ibaud : int ; (* Input baud rate.
2136 *)
2137 mutable c_csize : int ; (* Number of bits per character (5-8).
2139 *)
2140 mutable c_cstopb : int ; (* Number of stop bits (1-2).
2142 *)
2143 mutable c_cread : bool ; (* Reception is enabled.
2145 *)
2146 mutable c_parenb : bool ; (* Enable parity generation and detection.
2148 *)
2149 mutable c_parodd : bool ; (* Specify odd parity instead of even.
2151 *)
2152 mutable c_hupcl : bool ; (* Hang up on last close.
2154 *)
2155 mutable c_clocal : bool ; (* Ignore modem status lines.
2157 *)
2158 mutable c_isig : bool ; (* Generate signal on INTR, QUIT, SUSP.
2160 *)
2161 mutable c_icanon : bool ; (* Enable canonical processing (line buffer‐
2163 ing and editing)
2164 *)
2165 mutable c_noflsh : bool ; (* Disable flush after INTR, QUIT, SUSP.
2167 *)
2168 mutable c_echo : bool ; (* Echo input characters.
2170 *)
2171 mutable c_echoe : bool ; (* Echo ERASE (to erase previous character).
2173 *)
2174 mutable c_echok : bool ; (* Echo KILL (to erase the current line).
2176 *)
2177 mutable c_echonl : bool ; (* Echo NL even if c_echo is not set.
2179 *)
2180 mutable c_vintr : char ; (* Interrupt character (usually ctrl-C).
2182 *)
2183 mutable c_vquit : char ; (* Quit character (usually ctrl-\).
2185 *)
2186 mutable c_verase : char ; (* Erase character (usually DEL or ctrl-H).
2188 *)
2189 mutable c_vkill : char ; (* Kill line character (usually ctrl-U).
2191 *)
2192 mutable c_veof : char ; (* End-of-file character (usually ctrl-D).
2194 *)
2195 mutable c_veol : char ; (* Alternate end-of-line char. (usually none).
2197 *)
2198 mutable c_vmin : int ; (* Minimum number of characters to read before
2200 the read request is satisfied.
2201 *)
2202 mutable c_vtime : int ; (* Maximum read wait (in 0.1s units).
2204 *)
2205 mutable c_vstart : char ; (* Start character (usually ctrl-Q).
2207 *)
2208 mutable c_vstop : char ; (* Stop character (usually ctrl-S).
2210 *)
2211 }
2212 val tcgetattr : file_descr -> terminal_io
2218 Return the status of the terminal referred to by the given file de‐
2220 scriptor.
2221 type setattr_when = Unix.setattr_when =
2224 | TCSANOW
2225 | TCSADRAIN
2226 | TCSAFLUSH
2227 val tcsetattr : file_descr -> mode:setattr_when -> terminal_io -> unit
2233 Set the status of the terminal referred to by the given file descrip‐
2235 tor. The second argument indicates when the status change takes place:
2236 immediately ( TCSANOW ), when all pending output has been transmitted (
2237 TCSADRAIN ), or after flushing all input that has been received but not
2238 read ( TCSAFLUSH ). TCSADRAIN is recommended when changing the output
2239 parameters; TCSAFLUSH , when changing the input parameters.
2240 val tcsendbreak : file_descr -> duration:int -> unit
2244 Send a break condition on the given file descriptor. The second argu‐
2246 ment is the duration of the break, in 0.1s units; 0 means standard du‐
2247 ration (0.25s).
2248 val tcdrain : file_descr -> unit
2252 Waits until all output written on the given file descriptor has been
2254 transmitted.
2255 type flush_queue = Unix.flush_queue =
2258 | TCIFLUSH
2259 | TCOFLUSH
2260 | TCIOFLUSH
2261 val tcflush : file_descr -> mode:flush_queue -> unit
2267 Discard data written on the given file descriptor but not yet transmit‐
2269 ted, or data received but not yet read, depending on the second argu‐
2270 ment: TCIFLUSH flushes data received but not read, TCOFLUSH flushes
2271 data written but not transmitted, and TCIOFLUSH flushes both.
2272 type flow_action = Unix.flow_action =
2275 | TCOOFF
2276 | TCOON
2277 | TCIOFF
2278 | TCION
2279 val tcflow : file_descr -> mode:flow_action -> unit
2285 Suspend or restart reception or transmission of data on the given file
2287 descriptor, depending on the second argument: TCOOFF suspends output,
2288 TCOON restarts output, TCIOFF transmits a STOP character to suspend in‐
2289 put, and TCION transmits a START character to restart input.
2290 val setsid : unit -> int
2294 Put the calling process in a new session and detach it from its con‐
2296 trolling terminal.
2297OCamldoc 2021-01-26 UnixLabels(3)