From e9c0babd14ee5e2a52576a5ab3f1461171f1f8ae Mon Sep 17 00:00:00 2001
From: Tanguy MAZE <tmaze@student.42.fr>
Date: Sun, 28 Oct 2018 17:56:34 +0100
Subject: [PATCH] added open, close, read, write description to README.org

added non-exaustive description of file descriptor manipulating functions
---
 README.org | 106 +++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 94 insertions(+), 12 deletions(-)

diff --git a/README.org b/README.org
index 7ae3738..cab95ac 100644
--- a/README.org
+++ b/README.org
@@ -6,7 +6,7 @@
 #    By: tmaze <tmaze@student.42.fr>                +#+  +:+       +#+         #
 #                                                 +#+#+#+#+#+   +#+            #
 #    Created: 2018/10/26 13:33:24 by tmaze             #+#    #+#              #
-#    Updated: 2018/10/28 13:01:50 by tmaze            ###   ########.fr        #
+#    Updated: 2018/10/28 17:53:30 by tmaze            ###   ########.fr        #
 #                                                                              #
 # **************************************************************************** #
 
@@ -36,16 +36,98 @@
 	| =0=    | succès                      |
 	| =-1=   | erreur (met à jour =errno=) |
 
+** fonctions de manipulation de =file descriptors=
+*** =int open (const char *path, int oflag, ...)=
+	=#include <unistd.h>=
+
+	ouvre le fichier spécifié par =path= en lecture et/ou écriture selon =oflag=.
+	le =file descriptor= ainsi créé est retourné.
+**** l'argument =oflag=
+	 l'argument =oflag= permet de paramétrer le =fd= en liant différents flags
+	 par =or= (=|=).
+
+	 | valeur       | description                                |
+	 |--------------+--------------------------------------------|
+	 | =O_RDONLY=   | ouvrir le =fd= en leture seule             |
+	 | =O_WRONLY=   | ouvrir le =fd= en écriture seule           |
+	 | =O_RDWR=     | ouvrir le =fd= en lecture et écriture      |
+	 | =O_APPEND=   | commencer l'écriture en fin de fichier     |
+	 | =O_CREAT=    | créer le fichier si inexistant             |
+	 | =O_EXCL=     | erreur si O_CREAT                          |
+	 | =O_NOFOLLOW= | ne pas suivre les liens symboliques        |
+	 | =O_SYMLINK=  | authorise l'ouverture de liens symboliques |
+**** valeurs de retour
+	 En cas de succès, =open= retourne un entier positif désignant un =fd=.
+	 Sinon, la valeur =-1= est retournée et =errno= est modifiée pour indiquer l'erreur.
+
+*** =int close(int filedes)=
+	=#include <unistd.h>=
+
+	Supprime le descripteur =filedes= correctement.
+	Bien que si un process quitte, les =file descriptors= associés sont =free='d,
+	=clean= s'occupe aussi de rendre le =fd= réutilisable, le nombre maximum de
+	=fd= étant limité.
+**** valeurs de retour
+	 | valeur | escription                  |
+	 |--------+-----------------------------|
+	 | =0=    | succès                      |
+	 | =-1=   | erreur (met à jour =errno=) |
+	
+*** =ssize_t read(int filedes, void *buf, size_t nbyte)=
+	=#include <sys/types.h>=
+	=#include <sys/uio.h>=
+	=#include <unistd.h>=
+
+	Essaie de lire =nbyte= de données de l'objet référencé par =filedes= dans le
+	buffer =buf=.
+ 
+	Pour les objets capable de recherche, la lecture démarre à la position
+	indiquée par le pointeur associé à =filedes=. Après le retour de =read=,
+	ce pointeur est incrémenté du nombre d'octets lu.
+
+	Pour les objets non-capable de recherche, la lecture se fait toujours de la même
+	position et le pointeur associé à =filedes= est non-défini.
+
+**** valeurs de retour
+	 | valeur | description                 |
+	 |--------+-----------------------------|
+	 | =>0=   | succès (nb d'octets lus)    |
+	 | =0=    | succès et fin de fichier    |
+	 | =-1=   | erreur (met à jour =errno=) |
+
+*** =ssize_t write(int filedes, const void *buf, size_t nbyte)=
+	=#include <unistd.h>=
+
+	Essaie d'écrire =nbyte= de données sur l'objet référencé par =filedes= depuis le
+	buffer =buf=.
+
+	Pour les objets capable de recherche, l'écriture démarre à la position
+	indiquée par le pointeur associé à =filedes=. Après le retour de =write=,
+	ce pointeur est incrémenté du nombre d'octets écrits.
+
+	Pour les objets non-capable de recherche, l'écriture se fait toujours de la même
+	position et le pointeur associé à =filedes= est non-défini.
+
+	Si l'utilisateur n'est pas =super-user=, alors =write= supprime le bit =set-user-id=
+	du fichier. Ceci prévient une faille de sécurité où un utilisateur pourrais "capturer"
+	un =fd= ouvert sur un ficher appartenant au =super-user= disposant du bit =set-user-id=.
+
+**** valeurs de retour
+	 | valeur | description                 |
+	 |--------+-----------------------------|
+	 | =>0=   | succès (nb d'octets écrits) |
+	 | =0=    | succès et fin de fichier    |
+	 | =-1=   | erreur (met à jour =errno=) |
 
 * Todo list
-** TODO étudier les différents man du sujet
-   + [X] access
-   + [ ] open, close, read, write
-   + [ ] getcwd, chdir
-   + [ ] stat, lstat, fstat
-   + [ ] fork, execve
-   + [ ] wait, waitpid, wait3, wait4
-   + [ ] signal, kill
-   + [ ] exit
-   + [ ] environ
-   + [ ] builtin
+** TODO étudier les différents man du sujet [2/10]
+   - [X] access
+   - [X] open, close, read, write
+   - [ ] getcwd, chdir
+   - [ ] stat, lstat, fstat
+   - [ ] fork, execve
+   - [ ] wait, waitpid, wait3, wait4
+   - [ ] signal, kill
+   - [ ] exit
+   - [ ] environ
+   - [ ] builtin